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
Creating a verification
Face re-verification
These come fromPOST /v1/verifications when you send reference_verification_id; see Face re-verification. The body is {"error": {"code", "message"}}.
Consent, upload and submit
These come up only if you capture in your own UI.
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:
DOCUMENT_OUTLINE_NOT_FOUND, DOCUMENT_TOO_FAR, DOCUMENT_PORTRAIT_NOT_FOUND and DOCUMENT_BACK_SAME_AS_FRONT are not sent for every workspace; handle them anyway.
Reading results and blocking
Erasing personal data
These come fromDELETE /v1/verifications/{verification}/personal-data.
Calling again is always safe: an erasure that already happened answers
200 with the erased verification.
Test outcomes
Webhook subscriptions
Any endpoint
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 issubmitted. - Erasure: send it again. If the first one went through, the second answers
200with the erased verification.
Handling errors well
- Log the HTTP status, the
codeand themessage. - 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
4xxerrors other than429unchanged: they fail again.