Troubleshoot Network & HTTP
KEYRA-specific meaning of 400, 401, 403, 404, 409, 429, and 5xx.
On this page
Map status + error code together. Rate limits return rate_limited without Retry-After headers today.
429 from KEYRA API
Symptom
Requests return HTTP 429 with error rate_limited.
Most likely causes
- Aggressive polling
- Retry storms
- Shared key/IP exceeding the window
How to diagnose
- Partner body uses message; OAuth rate limit uses error_description
- No Retry-After headers are returned today
How to fix
- Use SDK wait helpers.
- Retry later with backoff.
Related errors: rate_limited
Related SDK: waitForChallengeApproval(), pollChallenge()
Related API: GET /v1/auth/challenge/{challengeId}
Related guides: Authentication
5xx from KEYRA API
Symptom
Requests return 503 feature_disabled or server_unavailable (or other 5xx).
Most likely causes
- Transient infrastructure
- Feature flag off
- Wrong auth deployment
How to diagnose
- Confirm auth host.
- Retry with backoff for server_unavailable.
How to fix
- Escalate if persistent with timestamp + endpoint + error code.
Related errors: server_unavailable, feature_disabled
Related guides: Environments
409 conflict errors
Symptom
already_enrolled, already_consumed, or verification_token_already_used.
Most likely causes
- Duplicate enroll
- Double consume/validate
- UI retry after success
How to diagnose
- Treat successful consume/validate as terminal.
- Start a new flow for a new login.
How to fix
- Do not retry the same token/code.
- Use status before enroll.
Related errors: already_enrolled, already_consumed, verification_token_already_used
Related SDK: consumeChallenge(), validateVerification(), get2FAStatus()
Related API: POST /v1/auth/challenge/{challengeId}/consume, POST /verify/validate, POST /v1/identities/enroll
Related guides: Verification, Server validation