Error Reference
Searchable catalog of verified KEYRA errors. Prefer troubleshooting by symptom when you do not have a code yet.
On this page
How to use this catalog
Each entry documents the wire or SDK code, HTTP status when applicable, likely causes, diagnosis steps, fix, retry guidance, and links into API / SDK / troubleshooting pages.
Don't have a code? Start at Troubleshooting.
Error codes
| Code | HTTP | Products | Meaning |
|---|---|---|---|
invalid_client | 401 | partner-2fa, oauth, shared | KEYRA rejected the client credentials or client id for this request. |
invalid_request | 400 | partner-2fa, oauth, shared | The request failed validation (missing/invalid fields). |
already_enrolled | 409 | partner-2fa | An active KEYRA identity already exists for this external user. |
invalid_return_url | 400 | partner-2fa | returnUrl failed Partner callback rules (typically origin match against project callback). |
not_enrolled | 404 | partner-2fa | No active KEYRA identity for this user — cannot start a challenge. |
not_found | 404 | partner-2fa | Unknown enrollment, identity, or challenge id for this project. |
invalid_token | 401 | partner-2fa, oauth | Token rejected — wrong, expired, or not valid for this operation. |
forbidden | 403 | partner-2fa | Operation rejected for project scope (e.g. consume across projects). |
project_mismatch | 403 | partner-2fa | Request body projectId does not match the authenticated API key’s project. |
already_consumed | 409 | partner-2fa | This Partner verificationToken was already consumed. |
expired | 401 / 410 | partner-2fa | Token, challenge, or enrollment link expired. |
rate_limited | 429 | partner-2fa, oauth, shared | Too many requests for this rate-limit bucket. |
server_unavailable | 503 | partner-2fa, oauth, shared | KEYRA cannot serve the request (e.g. database unavailable). |
feature_disabled | 503 | partner-2fa | Partner 2FA feature flag is off on the auth server. |
invalid_redirect_uri | 400 | oauth | redirect_uri is not an exact match of a registered callback URI. |
invalid_grant | 400 | oauth | Authorization code exchange failed (code, PKCE, redirect, or reuse). |
invalid_verification_token | 401 | oauth | POST /verify/validate rejected the verification/access token. |
verification_token_already_used | 409 | oauth | This OAuth verification token was already consumed by /verify/validate. |
popup_blocked | — | oauth | The browser blocked opening the KEYRA popup. |
popup_closed | — | oauth | The user closed the KEYRA popup before completion. |
verification_denied | — | oauth | Hosted verification reported denial / failure to the Web SDK. |
callback_state_missing | — | oauth | Redirect callback resumed without a state query parameter. |
invalid_state | — | oauth | Callback state does not match the value stored in the browser transient (CSRF protection). |
KeyraTimeoutError | — | partner-2fa, oauth, shared | An SDK wait helper exceeded its timeout before a terminal success. |
Error shapes
KEYRA surfaces are not a single JSON schema. Documented shapes from the current implementation:
| API area | Shape | Consistent? | Notes |
|---|---|---|---|
| Partner 2FA API | { "error": string, "message": string, "details"?: object } | Yes | Canonical via identityError helper. |
| OAuth start / token / userinfo | { "error": string, "error_description"?: string } | Yes | OAuth-style bodies. |
| OAuth /verify/validate failures | { "valid": false, "error": string } | Partial | Often omits error_description / message — harder for support logs. |
| OAuth rate limit | { "error": "rate_limited", "error_description": string } | Yes | Uses OAuth shape, not Partner message field. |
| Paste script | Error.message strings / onError | Partial | No stable typed code field; may surface API error_description when available. |
| Developer API observability | No requestId on Partner/OAuth developer errors | Partial | Link-session returns request_id but that is outside the public developer API catalog. |