Errors

Every error response has the same shape:

{ "detail": "A human-readable message." }

Branch on the HTTP status code, not on the message text.

Status	When
`400`	The `return_url` on `POST /verifications` is not on your registered allowlist.
`401`	The `Authorization` header is missing, malformed, or the API key was rejected.
`403`	The API key is valid but not enrolled as a verification client.
`404`	No verification with that `user_id` for you, or no document with that id on it.
`409`	The verification is in a state that forbids the action - for example, cancelling one that is already `completed`.
`422`	The request body failed validation (a malformed phone, a missing field).

Retrying safely

Reads (GET) are free and safe to poll and retry.
Create is idempotent per phone, so retrying POST /verifications never creates a duplicate.
Cancel is idempotent; cancelling an already-cancelled verification succeeds.

A 409 is not a transient error. It means the verification’s current status does not allow what you asked - re-read its status before deciding what to do next.

Get started

Concepts

Reference

Retrying safely

​Retrying safely

Retrying safely