Error codes¶

Every error response follows the OAuth 2.0 / OIDC convention:

json { "error": "invalid_request", "error_description": "Human-readable explanation", "error_uri": "https://developers.littlexlittle.org/reference/errors/#invalid_request" }

For redirect-based errors, the same fields appear as query parameters on the redirect_uri.

Standard OAuth 2.0 errors¶

Code	HTTP	When
`invalid_request`	400	Missing or malformed parameter.
`invalid_client`	401	`client_id` unknown, suspended, or wrong secret.
`invalid_grant`	400	Authorization code expired, used twice, or refresh token rotated/revoked.
`unauthorized_client`	400	Client is not allowed to use the requested grant type.
`unsupported_grant_type`	400	`grant_type` value isn't recognized.
`invalid_scope`	400	Requested scope is unknown or not allowed for this client.
`access_denied`	302 redirect	User declined consent.
`server_error`	500	Internal failure. Try again later; alert support if persistent.
`temporarily_unavailable`	503	Upstream maintenance window. Retry with backoff.

OIDC-specific errors¶

Code	When
`interaction_required`	`prompt=none` was used but the user must interact (consent/login).
`login_required`	`prompt=none` was used but no upstream session exists.
`account_selection_required`	`prompt=none` was used but multiple accounts match.
`consent_required`	`prompt=none` was used but consent is not yet granted.
`invalid_request_uri`	`request_uri` is not allowed.
`invalid_request_object`	The signed request object failed verification.
`request_not_supported`	Server doesn't support `request` parameter.
`request_uri_not_supported`	Server doesn't support `request_uri` parameter.
`registration_not_supported`	Self-serve registration is closed (current state).

Little X Little custom errors¶

Code	When
`lxl_tenant_mismatch`	Account belongs to a different NGO than the client.
`lxl_app_suspended`	The NGO app for this client is currently suspended.
`lxl_user_suspended`	The user account is suspended.
`lxl_rate_limited`	Too many requests. See `Retry-After` header.
`lxl_pkce_required`	Public client did not include `code_challenge`.

Handling tips¶

Do not retry on invalid_grant. The user must re-authenticate.
Always retry on temporarily_unavailable with exponential backoff (start 1s, max 5m, jitter ±20%).
Log error_uri — it links to this page anchored at the specific code.
Show error_description to developers, not end users. Translate to friendly copy in your UI.