Errors & Troubleshooting
Use API codes when you have them; use symptoms when the failure is in the browser UX.
On this page
API error codes
OAuth Verify endpoints return structured errors. Common codes from start, token, and validate:
| Error | HTTP | Where | Meaning | Fix |
|---|---|---|---|---|
invalid_redirect_uri | 400 | Start | redirect_uri not exact match of project_callback_url or project_hosted_redirect_uris[] | Register the exact URI; check trailing slash / scheme |
invalid_client | 401 | Validate (and related) | Client id rejected for the token / request | Use the publishable id that started the flow |
invalid_verification_token | 401 | /verify/validate | Unknown, expired, or malformed token | Send the fresh access_token from exchange |
verification_token_already_used | 409 | /verify/validate | Token already consumed in keyra_verification_token_consumptions | Start a new login; do not retry validate with the same token |
Web SDK errors
| Class / code | When | Retry? |
|---|---|---|
KeyraOAuthError · popup_blocked | Browser blocked the popup | Yes — fall back to redirect |
KeyraOAuthError · popup_closed | User closed the popup | Yes — user-initiated retry |
KeyraOAuthError · verification_denied | User denied / failed hosted verification | Yes — new verify |
KeyraOAuthError · callback_state_missing | Redirect callback missing state | Restart flow; do not invent state |
KeyraOAuthError · invalid_state | state mismatch vs stored transient | Restart flow; check sessionStorage not cleared |
KeyraTimeoutError | Exceeded timeoutMs (default 120000) | Optional — new verify |
Paste script errors
- Failures invoke
onError. Popup path may also deliverKEYRA_AUTH_ERRORviapostMessage(origin-checked againstauthOrigin). - Redirect PKCE missing from
keyra:oauth:flow:v2→ callback cannot complete exchange. - Required options missing (
authOrigin,clientId,redirectUri) fail before start.
Troubleshooting by symptom
Start fails with invalid_redirect_uri
- Possible cause: URI not registered; trailing slash; http vs https; wrong project.
- Fix: Exact match against primary callback or hosted redirect URIs list.
Button click does nothing / popup never opens
- Possible cause: Popup blocker; click handler not a direct user gesture.
- Fix: Open from click; catch
popup_blocked; switch tomode: "redirect".
Redirect returns but login does not finish
- Possible cause: Missing
handleRedirectCallback/completeRedirectCallback; clearedsessionStorage;invalid_state. - Fix: Run callback completion on the exact
redirectUripage; preserve storage keyskeyra_sdk_transient/keyra:oauth:flow:v2.
User verified but app session never appears
- Possible cause: Backend skipped
/verify/validate; token never POSTed; validate failed silently. - Fix: Require validate →
valid: true→ create your session. See Server validation.
Second login attempt with same token fails 409
- Possible cause: Expected — single-use consumption.
- Fix: Start a new OAuth Verify flow for each login; use your session afterward.
Token exchange fails after successful hosted UI
- Possible cause: Verifier lost; wrong
redirect_urion exchange; code already used. - Fix: Keep PKCE material across redirect; exchange once with matching URI — PKCE.