> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.withverifa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.withverifa.com/_mcp/server.

# Errors

> Error response format and status codes.

All error responses follow a consistent JSON format:

```json
{
  "error": "not_found",
  "detail": "Session not found.",
  "status_code": 404
}
```

| Field         | Type    | Description                              |
| ------------- | ------- | ---------------------------------------- |
| `error`       | string  | Machine-readable error code.             |
| `detail`      | string  | Human-readable description of the error. |
| `status_code` | integer | HTTP status code.                        |

## Status codes

| Code  | Meaning               | When it occurs                                                                                                                                                                                              |
| ----- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Bad Request           | Malformed JSON, missing required fields, or invalid parameter values.                                                                                                                                       |
| `401` | Unauthorized          | Missing or invalid API key.                                                                                                                                                                                 |
| `403` | Forbidden             | API key lacks the required scope, or IP not in allowlist.                                                                                                                                                   |
| `404` | Not Found             | The requested resource does not exist or belongs to a different organization.                                                                                                                               |
| `409` | Conflict              | Resource state conflict (e.g. approving an already-approved session).                                                                                                                                       |
| `422` | Unprocessable Entity  | Request body is valid JSON but fails semantic or field-level validation (e.g. string longer than its `maxLength`, list longer than its `maxItems`, or an idempotency key reused with different parameters). |
| `429` | Too Many Requests     | Rate limit or product quota exceeded. See [Rate Limiting](/api-details/rate-limiting).                                                                                                                      |
| `500` | Internal Server Error | An unexpected error on our side. These are automatically reported and investigated.                                                                                                                         |

## Common error codes

| `error` value          | Status | Description                                          |
| ---------------------- | ------ | ---------------------------------------------------- |
| `bad_request`          | 400    | Invalid request parameters.                          |
| `unauthorized`         | 401    | Missing or invalid API key.                          |
| `forbidden`            | 403    | Insufficient permissions.                            |
| `not_found`            | 404    | Resource not found.                                  |
| `conflict`             | 409    | State conflict.                                      |
| `validation_error`     | 422    | Semantic validation failure.                         |
| `idempotency_mismatch` | 422    | Same idempotency key used with different parameters. |
| `rate_limited`         | 429    | Rate limit exceeded.                                 |
| `quota_exceeded`       | 429    | Product quota exceeded.                              |
| `internal_error`       | 500    | Unexpected server error.                             |

## Field-level validation (422)

Request bodies for sessions, cases, identities, and screening enforce strict
field bounds. Violations return `422 Validation Error` with a `detail` array
naming each offending field. Common triggers:

* String fields exceeding their `maxLength` (typically 100, 500, or 5000
  characters depending on the field).
* Lists exceeding their `maxItems` (typically 50 tags or 100 items).
* The `metadata` object exceeding 16 KB serialized.

Fix the request body before retrying — these errors are not transient.

## Retry guidance

| Status code        | Retry? | Notes                                                     |
| ------------------ | ------ | --------------------------------------------------------- |
| 400, 401, 403, 404 | No     | Fix the request before retrying.                          |
| 409                | No     | Resolve the conflict (e.g. check current resource state). |
| 422                | No     | Fix the request body or use a new idempotency key.        |
| 429                | Yes    | Wait for the `Retry-After` duration, then retry.          |
| 500                | Yes    | Retry with exponential backoff (max 3 attempts).          |

## Related

* [Authentication](/api-details/authentication) — 401 and 403 error details
* [Rate Limiting](/api-details/rate-limiting) — 429 response handling and quotas
* [Idempotency](/api-details/idempotency) — 422 idempotency mismatch errors