Errors and reason codes

API errors

Errors are RFC 9457 application/problem+json with a stable code:

Copied

{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "The flow_id field is required.",
  "code": "validation_failed",
  "errors": { "flow_id": ["The flow_id field is required."] },
  "request_id": "01J..."
}

Branch on code, not on the text. Quote request_id when you write to support.

`code`	HTTP	Meaning
`unauthenticated`	401	Missing, invalid or expired token
`missing_ability`	403	The token lacks the needed ability
`forbidden`	403	The token's owner has no right to do this in the team
`not_found`	404	No such resource in this team and mode
`team_required` / `team_not_found`	400 / 404	Send the `X-Team-Id` header, or it is not one of the user's teams
`validation_failed`	422	See `errors`
`flow_not_ready`	422	The flow is archived or incomplete (for example no privacy policy URL)
`quota_exceeded`	402	No plan, trial used up, included verifications used with overage off, or overage cap reached; `quota.reason` says which
`not_cancellable` / `not_relinkable`	409	The session is no longer in a state that allows it
`idempotency_key_reused`	422	The same `Idempotency-Key` was sent with a different request
`rate_limited`	429	Wait for `Retry-After` seconds
`token_in_query`	400	Tokens go in the `Authorization` header only

Reason codes

reason_codes on a rejection or resubmission request are stable machine values. Treat unknown ones as other.

Code	Meaning
`doc_unreadable`	Document images are blurry, cut off or unreadable
`doc_expired`	The document is expired or has too little validity
`doc_not_accepted`	Document type or country not accepted by the flow
`doc_tampered_suspected`	Signs of alteration
`selfie_mismatch`	The selfie does not look like the person on the document
`selfie_unclear`	The selfie is dark, blurry, covered or shows several people
`liveness_challenge_failed`	The video does not show the requested challenge
`liveness_screen_replay_suspected`	The video looks like a recording of a screen or photo
`poa_name_mismatch`	The name on the proof of address differs from the document
`poa_too_old`	The proof of address is older than allowed
`poa_unreadable`	The proof of address is unreadable
`under_age`	Under the flow's minimum age
`duplicate_suspected`	The same document was used in another session of your account
`other`	Other reason

The applicant sees a friendly text for each code, never the internal wording.