Errors

All errors return JSON: {"detail": "human-readable reason"}.

Status	Where	Cause	Handle
401	Backend endpoints	Missing/invalid API key	Fix credentials; check for whitespace in the header
401	Capture endpoints	Missing, expired (30 min), or revoked handoff token	Restart the flow: create a new verification via your backend
404	Any {id} endpoint	Unknown verification ID	Check the ID; erased verifications still exist (their data doesn’t)
409	POST /v1/capture/document	Already past document stage	Call GET /v1/capture/status, resume from next_step
409	POST /v1/capture/selfie	Document not uploaded yet, or frame for that step already uploaded	Same — status, then resume
409	POST /v1/capture/challenge	Called before document upload	Upload the document first
409	POST /v1/attestations/{id}	Verification not approved	Wait for the decision webhook
409	POST /v1/review/{id}	Not in manual_review (already decided)	Refresh the queue
413	Uploads	File over 15 MB	Compress client-side (JPEG q≈0.9 is plenty)
415	Uploads	Not JPEG/PNG/WebP	Convert before upload
422	Uploads	Under 1 KB (junk capture)	Re-capture
422	POST /v1/capture/selfie	step outside 0..N-1	Use indices from the challenge response
422	POST /v1/verifications	Non-HTTPS webhook_url	Use HTTPS
422	POST /v1/attestations/{id}	Unknown claim name	See the claim catalogue
422	POST /v1/review/{id}	Missing/short note, or bad decision value	Notes are mandatory — write a real one
429	Anywhere	Rate limit (40/min capture, 240/min API per IP)	Back off per Retry-After
500	Anywhere	Server fault	Retry with backoff; check /health; a pipeline 500 routes the verification to manual review rather than losing it

Debugging tips

• Device-side 401 right after creation almost always means the token was URL-mangled — pass it verbatim, it’s URL-safe base64.
• A verification “stuck” in processing for minutes: check server logs for verification.pipeline_error audit events — the fail-safe should have routed it to review; if not, that’s a bug worth reporting.
• Webhook never arrived: your endpoint must answer 2xx in <10 s across 3 attempts; reconcile by polling GET /v1/verifications/{id}.