Error reference

How to use this page

This is a scannable lookup that maps each error to its HTTP status, where it appears, the likely cause, whether it is worth retrying, and the fix. For step-by-step diagnosis and worked examples, follow the links to the detailed pages: Common errors, OAuth and OIDC error codes, Token validation issues, and Redirect and domain issues.

Always capture the Support ID from the error before raising a ticket - see Diagnose a failing request.

Authorisation endpoint errors (returned on the redirect)

These arrive as error query parameters on your redirect_uri.

error	HTTP	Likely cause	Retry?	Fix
invalid_request	302	Missing/malformed parameter (e.g. no scope=openid, bad redirect_uri, missing PKCE)	No	Correct the request; PKCE (S256) is required for all clients
unauthorized_client	302	The client is not allowed to use this flow	No	Check the Application registration with LuxID
access_denied	302	User cancelled, or cannot satisfy the requested auth_level (no eligible factor)	No	Offer enrolment; do not auto-retry in a loop
unsupported_response_type	302	response_type other than code/none (e.g. implicit)	No	Use response_type=code with PKCE
invalid_scope	302	scope missing openid or otherwise invalid	No	Send a valid scope (openid minimum)
interaction_required / login_required / consent_required	302	prompt=none used but interaction is needed	No	Re-run interactively (drop prompt=none)
unmet_authentication_requirements	302	Requested acr_values cannot be met by any available method	No	Lower the requirement or guide the user to enrol the needed factor
server_error	302	Transient LuxID-side error	Yes	Backoff + retry; contact LuxID if it persists
temporarily_unavailable	302	LuxID temporarily overloaded/maintenance	Yes	Honour Retry-After; backoff

Token endpoint errors (JSON body)

Returned from POST /mga/sps/oauth/oauth20/token with an error field.

error	HTTP	Likely cause	Retry?	Fix
invalid_request	400	Missing/duplicate parameter, malformed body	No	Fix the request
invalid_client	401	Bad/expired client_secret, or wrong client auth method	No	Check/rotate the Client Secret
invalid_grant	400	Code already used/expired, redirect URI mismatch, refresh token already rotated/revoked, or concurrent refresh lost the race	No	Start a fresh authorisation; serialise refreshes
unauthorized_client	400	Client not permitted to use this grant type	No	Check the Application registration
unsupported_grant_type	400	Grant not supported (e.g. client_credentials on the user tenant, password)	No	Use authorization_code or refresh_token; for M2M see the Partner API

Bearer-token (UserInfo / API) errors

Returned via the WWW-Authenticate header.

Condition	HTTP	Likely cause	Retry?	Fix
invalid_token	401	Access token expired, malformed, or revoked	No	Refresh the token, then retry the call once
insufficient_scope	403	Token lacks the required scope for the resource	No	Request the appropriate scope at authorisation time

Platform errors

Error	HTTP	Likely cause	Retry?	Fix
FEATURE_DISABLED ({"type":"FEATURE_DISABLED","message":"Feature disabled"})	403	The Application hit an endpoint for a feature not enabled for your Partner	No	Request enablement via LuxID
redirect_uri_mismatch	400/302	The request redirect_uri does not exactly match a registered value (scheme, host, port, path, trailing slash)	No	Align the request to the registered URI; see Redirect and domain issues
Rate limited	429	Too many requests	Yes	Honour Retry-After; reduce rate. See Calling LuxID reliably
Service error	5xx	Transient LuxID-side error	Yes	Backoff + retry; contact LuxID if it persists

ID-token validation failures (client-side)

These are not HTTP errors - they are checks your application performs after receiving a token. Reject the token if any fail.

Check	Failure cause	Fix
Signature (RS256, by kid)	Wrong/rotated key, tampered token	Refresh JWKS once; reject if still invalid. See Key management
iss	Not exactly https://login.luxid.lu	Reject - not issued by LuxID
aud / azp	Token issued to another client	Reject (token substitution)
exp	Expired (allow ≤ 60 s clock skew)	Re-authenticate or refresh
nonce	Does not match the value you sent	Reject (replay)
acr	Below your required auth_level	Step up; never assume the requested level was reached

See Token validation issues for code samples.

Related pages

• Common errors
• OAuth and OIDC error codes
• Token validation issues
• Redirect and domain issues
• Calling LuxID reliably