Errors

An error has an HTTP status and, in most cases, a machine-readable code. The body comes in one of four shapes, described in the API reference; read error.code, then code, then fall back to the status. The server SDKs do this for you and raise one exception type. These are request errors. Why a verification was declined is not an error: it is the verification’s reason, listed in Decision reasons.

Authentication

HTTP	Code	What to do
401	`MISSING_API_KEY`	Send `X-API-Key`.
401	`INVALID_API_KEY`	Check the key; test and live keys differ.
401	`NO_SECRET_KEYS`	Create a secret key for the workspace in the console.
401	`MISSING_SIGNATURE`	Sign the request.
401	`INVALID_SIGNATURE`	See when the signature does not match.
403	`WORKSPACE_SUSPENDED`	The workspace is suspended; reactivate it in the console.
403	`TENANT_ARCHIVED`	The account is closed. Contact support.

Creating a verification

HTTP	Code	What to do
402	`PAYMENT_METHOD_REQUIRED`	The free verifications are used up (or a deadline set on your account has passed). Add a payment method in the console to create live verifications. The body also has `free_verifications_remaining`, `trial_ends_at` and `trial_active`.
422	—	A field is invalid; `errors` names it.

These come up only if you capture in your own UI.

HTTP	Code	What to do
403	`CONSENT_REQUIRED`	Record the person’s consent before uploading.
402	`PAYMENT_METHOD_REQUIRED`	On submit: the account had no way to pay any more (the payment method was removed, or a deadline set on your account passed) after the verification was created. Running out of free verifications alone does not cause this: verifications created before they ran out still complete. Add a payment method, then submit again.
422	`MAX_ATTEMPTS_REACHED`	A facial age estimation that moved to a document has no attempts left for a new selfie. Create a new verification.
422	`INVALID_STATUS`	The verification is not in a state that can be submitted, or belongs to another workspace.
422	`MISSING_REQUIRED_MEDIA`	Upload the missing images, then submit.
422	`VALIDATION_ERROR`	A field is invalid.
422	—	A field is invalid, or a document image arrived after every required image was already in: `errors` names it.
403	—	`{"message": "Access denied to this verification."}` on consent: the verification belongs to another workspace.

An upload is checked as soon as it arrives. If the image is not usable, the upload fails with 422 and a code the person can act on; ask them to retake it:

Code	Ask the person to
`FACE_NOT_FOUND`	Show their face in the frame.
`FACE_INVALID_SIZE`	Move so the face fills the frame, not too close or too far.
`FACE_TOO_BLURRY`	Hold still, in focus.
`FACE_BRIGHTNESS_INVALID`	Find even light, neither too dark nor too bright.
`FACE_OCCLUDED`	Remove anything covering the face.
`FACE_ALIGNMENT_FAILED`, `FACE_TOO_TILTED`	Look straight at the camera.
`FACE_EYES_CLOSED`	Keep their eyes open.
`FACE_QUALITY_UNSUITABLE`, `FACE_VALIDATION_FAILED`	Retake the selfie.
`DOCUMENT_NOT_FOUND`, `DOCUMENT_OUTLINE_NOT_FOUND`	Show the whole document on a plain surface.
`DOCUMENT_TOO_FAR`	Bring the document closer.
`DOCUMENT_PORTRAIT_NOT_FOUND`	Show the side of the document with their photo (a closed passport cover or the back of a card has none), fully in the frame, in good light and without glare.
`DOCUMENT_TOO_BLURRY`	Hold the document still, in focus.
`DOCUMENT_BRIGHTNESS_INVALID`	Avoid glare and shadow.
`DOCUMENT_NOT_READABLE`, `DOCUMENT_VALIDATION_FAILED`	Retake the document so the text is readable.

DOCUMENT_OUTLINE_NOT_FOUND, DOCUMENT_TOO_FAR and DOCUMENT_PORTRAIT_NOT_FOUND are not sent for every workspace; handle them anyway.

Reading results and blocking

HTTP	Code	What to do
404	—	`{"message": "Resource not found"}`: the verification or image does not exist.
403	—	`{"message": "Access denied to this verification."}`: reading a verification, its document, its estimation or its media with the key of another workspace.
404	`MEDIA_NOT_FOUND`	The image was deleted by retention or erasure.
403	`FACE_BLOCKLIST_DISABLED`	The face blocklist is not enabled for your account.
403	`VERIFICATION_MISMATCH`	Blocking a face: the verification belongs to another workspace.
422	`VALIDATION_ERROR`	Blocking a face: `reason_code` is unknown, or there is nothing to block; see Face blocklist. This body has both `error` and `errors`.

Test outcomes

HTTP	Code	What to do
403	`TEST_WORKSPACE_ONLY`	Setting a test outcome works in a test workspace only.
422	`INVALID_STATUS`	The verification is already final (`approved`, `declined`, `abandoned`, `expired`), or already in `review` when you set `review`. Create a new verification, or set another outcome on one in review.

Webhook subscriptions

HTTP	Code	What to do
422	`WEBHOOK_SUBSCRIPTION_LIMIT`	The workspace already has 50 webhook subscriptions. Delete one you no longer use.
422	—	The `url` breaks the webhook URL rules, or `statuses` holds a status that is not a decision: `errors` names the field.
404	—	`{"message": "Resource not found"}`: deleting a subscription that does not exist in this workspace.

Any endpoint

HTTP	Code	What to do
429	`RATE_LIMIT`	Wait `Retry-After` seconds; see Rate limiting.
5xx	—	Retry a `GET` with backoff. See below for a `POST`.

When a request times out

There is no idempotency key.

Create: create again. An unused verification is never started, expires after seven days and is not billed: a verification is billed when it is submitted.
Consent: send it again; the same values answer 200.
Upload: upload again; the new image replaces the previous one of the same type and side.
Submit: send it again. If the first one went through, the second answers 422 INVALID_STATUS: read the verification to confirm it is submitted.

Handling errors well

Log the HTTP status, the code and the message.
Show the person a message for the upload codes above; show a generic message for everything else and fix the cause on your side.
Do not retry 4xx errors other than 429 unchanged: they fail again.

Guides

Recipes

Model Context Protocol (MCP)

Web

Server SDKs

Integrations

Authentication

Creating a verification

Reading results and blocking

Test outcomes

Webhook subscriptions

Any endpoint

When a request times out

Handling errors well

​Authentication

​Creating a verification

​Consent, upload and submit

​Reading results and blocking

​Test outcomes

​Webhook subscriptions

​Any endpoint

​When a request times out

​Handling errors well

Authentication

Creating a verification

Consent, upload and submit

Reading results and blocking

Test outcomes

Webhook subscriptions

Any endpoint

When a request times out

Handling errors well