> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verify.privue.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Status codes the verification API returns and what they mean.

Every error response has the same shape:

```json theme={null}
{ "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 `verification_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.