Error and edge-case UX
Overview
When something goes wrong during the LuxID sign-in flow, users land on a screen in your application that your team wrote. The quality of that message - its tone, clarity, and actionability - determines whether the user retries successfully or abandons.
This page provides:
- A description of each error state your application may encounter
- Recommended microcopy in English, French, German, and Luxembourgish
- Guidance on when to show each message and what action to offer
For error messages shown by LuxID itself (on login.luxid.lu), you do not control the copy. For messages shown by your application after receiving an error callback, these guidelines apply.
Error states reference
User cancelled at the consent screen
How it arrives: LuxID redirects to your redirect_uri with error=access_denied.
What happened: The user clicked "Cancel" or "Decline" on the consent screen. This is an intentional user action, not a system failure.
Recommended UX:
- Return the user to your application's sign-in page or the page they came from.
- Display a calm, non-judgmental message.
- Offer a clear path to try again.
- Do not treat this as a system error or display a generic error page.
Microcopy:
| Language | Heading | Body | Button |
|---|---|---|---|
| EN | Sign-in cancelled | You chose not to sign in with LuxID. You can try again whenever you're ready. | Try again |
| FR | Connexion annulée | Vous avez choisi de ne pas vous connecter avec LuxID. Vous pouvez réessayer quand vous le souhaitez. | Réessayer |
| DE | Anmeldung abgebrochen | Sie haben sich entschieden, sich nicht mit LuxID anzumelden. Sie können es jederzeit erneut versuchen. | Erneut versuchen |
| LB | Umellen ofgebrach | Dir hutt Iech entscheet, Iech net mat LuxID umzellen. Dir kënnt et jidderzeiss nach eng Kéier probéieren. | Nach eng Kéier probéieren |
Network failure during the callback
How it arrives: The redirect back to your redirect_uri fails due to a network timeout, the user's connection dropping, or a server error on your side.
What happened: The authorisation code was issued but your server did not receive it (or could not exchange it).
Recommended UX:
- Prompt the user to try again from the beginning. Do not attempt to replay a failed callback with stale parameters.
- If the failure is on your server (5xx), display a service-unavailable message and log the error.
Microcopy:
| Language | Heading | Body | Button |
|---|---|---|---|
| EN | Connection problem | Something went wrong while completing sign-in. Please try again. | Try again |
| FR | Problème de connexion | Une erreur s'est produite lors de la finalisation de la connexion. Veuillez réessayer. | Réessayer |
| DE | Verbindungsproblem | Beim Abschluss der Anmeldung ist ein Fehler aufgetreten. Bitte versuchen Sie es erneut. | Erneut versuchen |
| LB | Verbindungsproblem | E Feeler ass opgetrueden wärend d'Umellen ofgeschloss gouf. Probéiert et nach eng Kéier. | Nach eng Kéier probéieren |
Expired session or state mismatch
How it arrives: Your server receives a callback with an expired code, a state parameter that does not match what you sent, or a PKCE verifier that fails validation.
What happened: The user took too long to complete the flow (typically more than 10 minutes on the LuxID page), navigated back and forward in their browser, or used a bookmark of a mid-flow URL.
Recommended UX:
- Restart the flow from the beginning - redirect the user to
/mga/sps/oauth/oauth20/authorizeagain. - Display a brief explanation that does not mention internal parameters.
Microcopy:
| Language | Heading | Body | Button |
|---|---|---|---|
| EN | Your sign-in session expired | This happens if you took a while to complete sign-in or navigated away. Please start again. | Start again |
| FR | Votre session de connexion a expiré | Cela arrive si vous avez mis du temps à vous connecter ou si vous avez navigué ailleurs. Veuillez recommencer. | Recommencer |
| DE | Ihre Anmeldesitzung ist abgelaufen | Das passiert, wenn die Anmeldung zu lange gedauert hat oder Sie die Seite verlassen haben. Bitte starten Sie erneut. | Erneut starten |
| LB | Är Umell-Sessioun ass ofgelaf | Dat geschitt wann Dir ze laang gebraucht hutt oder wann Dir op eng aner Säit gaangen sidd. Fänkt w.e.g. nach eng Kéier un. | Nach eng Kéier ufänken |
Invalid redirect URI
How it arrives: LuxID rejects the authorisation request with error=redirect_uri_mismatch because the redirect_uri your server sent does not match any URI registered for your application with LuxID.
What happened: This is a configuration error, not a user error. It typically occurs in development/staging environments, after a domain change, or after a deployment misconfiguration.
Recommended UX:
- This error should not be visible to end users in production. If it is, your application has a configuration problem.
- In development, display a developer-friendly message.
- In production, display a generic service-unavailable message and alert your engineering team.
Microcopy (production, shown to users):
| Language | Heading | Body |
|---|---|---|
| EN | Sign-in is temporarily unavailable | We're working to fix this. Please try again later or contact support. |
| FR | La connexion est temporairement indisponible | Nous travaillons à résoudre ce problème. Veuillez réessayer plus tard ou contacter le support. |
| DE | Die Anmeldung ist vorübergehend nicht verfügbar | Wir arbeiten an einer Lösung. Bitte versuchen Sie es später erneut oder kontaktieren Sie den Support. |
| LB | D'Umellen ass viriwwerhend net verfügbar | Mir schaffen un enger Léisung. Probéiert et méi spéit nach eng Kéier oder kontaktéiert den Support. |
Developer-facing log: include the specific error (redirect_uri_mismatch), the URI your server sent, and the registered URIs for your client_id.
Account blocked
How it arrives: LuxID returns error=account_locked (or the equivalent status in the token response) after too many failed authentication attempts. Note that the literal API error code remains account_locked; only the user-facing wording uses "blocked", consistent with the user-facing help and the FR/DE/LB microcopy below.
What happened: The user's account has been temporarily blocked as a security measure. LuxID will automatically remove the block after a cooling-off period, or the user can reset their password to regain access immediately.
Recommended UX:
- Explain the block clearly without making the user feel blamed.
- Link to the password reset flow.
- Do not expose the exact block duration (it is variable and could be exploited).
Microcopy:
| Language | Heading | Body | Action |
|---|---|---|---|
| EN | Account temporarily blocked | For security, your LuxID Account has been temporarily blocked after several unsuccessful sign-in attempts. Reset your password to regain access. | Reset your LuxID password (opens in a new tab) |
| FR | Compte temporairement bloqué | Pour des raisons de sécurité, votre compte LuxID a été temporairement bloqué après plusieurs tentatives de connexion infructueuses. Réinitialisez votre mot de passe pour récupérer l'accès. | Réinitialiser votre mot de passe LuxID (opens in a new tab) |
| DE | Konto vorübergehend gesperrt | Aus Sicherheitsgründen wurde Ihr LuxID-Konto nach mehreren fehlgeschlagenen Anmeldeversuchen vorübergehend gesperrt. Setzen Sie Ihr Passwort zurück, um wieder Zugang zu erhalten. | LuxID-Passwort zurücksetzen (opens in a new tab) |
| LB | Kont temporär gespaart | Aus Sécherheetsgrënn gouf Äre LuxID-Kont no mehreren erfolglosen Umellversuche temporär gespaart. Setze Äert Passwuert zréck fir den Zougang erëm ze kréien. | LuxID-Passwuert zrécksetzen (opens in a new tab) |
Risk score escalated - MFA required
How it arrives: LuxID's risk engine determined that the session requires a second factor, but the user either does not have one enrolled or failed the MFA challenge.
What happened: LuxID required a step-up challenge based on contextual security signals. The user needs to verify their identity with a second factor.
Recommended UX:
- If LuxID itself handles the MFA step-up (which it does for enrolled users), this error will not reach your application.
- If the user has no MFA enrolled and your application requires
acr_values=urn:luxid:acr:level:substantial(the accepted request values are agreed per Partner during onboarding), LuxID will prompt for enrolment. Handle the case where enrolment is abandoned.
Microcopy (enrolment abandoned):
| Language | Heading | Body | Action |
|---|---|---|---|
| EN | Additional verification required | To access [Application Name], you need to set up a second sign-in method on your LuxID Account. | Set up verification in LuxID Account (opens in a new tab) |
| FR | Vérification supplémentaire requise | Pour accéder à [Nom de l'application], vous devez configurer une deuxième méthode de connexion sur votre compte LuxID. | Configurer la vérification dans LuxID (opens in a new tab) |
| DE | Zusätzliche Verifizierung erforderlich | Um auf [Anwendungsname] zuzugreifen, müssen Sie eine zweite Anmeldemethode in Ihrem LuxID-Konto einrichten. | Verifizierung in LuxID einrichten (opens in a new tab) |
| LB | Zousätzlech Verifikatioun erfuerderlech | Fir op [Applikatiounsnamm] zouzegräifen, musst Dir eng zweet Umellmethod an Ärem LuxID-Kont opsetzen. | Verifikatioun a LuxID opsetzen (opens in a new tab) |
LuxID service unavailable
How it arrives: https://login.luxid.lu is unreachable or returns a 5xx response, preventing the authorisation flow from starting.
What happened: LuxID is experiencing an outage or maintenance window.
Recommended UX:
- Detect this on your side by catching errors when initiating the redirect to LuxID.
- Display a graceful fallback. Do not display a raw HTTP error or stack trace.
Microcopy:
| Language | Heading | Body |
|---|
| EN | Sign in with LuxID is temporarily unavailable | We're aware of the issue. Please try again shortly. | | FR | La connexion avec LuxID est temporairement indisponible | Nous avons connaissance du problème. Veuillez réessayer dans quelques instants. | | DE | Die Anmeldung mit LuxID ist vorübergehend nicht verfügbar | Wir sind uns des Problems bewusst. Bitte versuchen Sie es in Kürze erneut. | | LB | D'Umellen mat LuxID ass viriwwerhend net verfügbar | Mir sinn eis dem Problem bewosst. Probéiert et kuerz duerno nach eng Kéier oder kuckt op der LuxID-Statussäit no Aktualiséierungen. |
General tone guidelines
Across all error states, apply the following tone principles:
- Calm and factual - avoid alarm words ("error", "failed", "problem") where a softer alternative exists ("unavailable", "cancelled", "expired").
- Blame-neutral - never imply user fault unless the user deliberately cancelled.
- Actionable - every error message must offer at least one concrete next step.
- Brief - one sentence of explanation plus one call-to-action is enough. Users do not read error walls.
- No jargon - no OAuth error codes (
access_denied,redirect_uri_mismatch) in user-facing copy. Log these internally.
Related pages
- Common errors - developer-facing error reference
- Consent screen design - handling the
access_deniedcancel case - Multi-factor UX - MFA failure and recovery paths
- Accessibility and localisation -
langfor matching error language to user language