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

# Errors and retries

> Read Threetone API error responses, retain request IDs, and retry only transient failures.

Threetone uses standard HTTP status codes. Read the response body before deciding whether to change the request or retry it.

## API error response

Authentication, authorization, conflict, not-found, and server errors use a `detail` object:

```json theme={null}
{
  "detail": {
    "status": "invalid_api_key",
    "message": "Invalid API key",
    "request_id": "req_01J..."
  }
}
```

The `status` value is machine readable. The `message` explains the failure, and `request_id` identifies the request in Threetone logs.

## Validation error response

A `422 Unprocessable Entity` response uses a list of validation errors:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

Use `loc` to find the invalid path, query parameter, header, or request-body field. Correct the request before sending it again.

## Common status codes

| Status | Meaning                                                         | Action                                                     |
| ------ | --------------------------------------------------------------- | ---------------------------------------------------------- |
| `400`  | The request cannot be processed as submitted.                   | Correct the request.                                       |
| `401`  | Authentication is missing or invalid.                           | Check the `x-api-key` header.                              |
| `403`  | The credential lacks access.                                    | Check permissions, workspace access, and key restrictions. |
| `404`  | The resource was not found or is not visible to the credential. | Check the identifier and workspace.                        |
| `409`  | The request conflicts with the current resource state.          | Refresh the resource and resolve the conflict.             |
| `422`  | One or more inputs failed validation.                           | Fix the fields listed in `detail`.                         |
| `429`  | The request exceeded a rate limit.                              | Wait for `Retry-After` before retrying.                    |
| `500`  | The server could not complete the request.                      | Retry only when the operation is safe to repeat.           |

## Retry safely

Retry transient `429` and `5xx` responses with exponential backoff and jitter. Honor `Retry-After` when present.

Before retrying a mutation, check whether the endpoint supports an idempotency key or whether the resource was already created or updated. Do not automatically retry a validation, authentication, authorization, or not-found response.

Keep the `X-Request-Id` response header, status code, method, path, and timestamp for any failure that needs investigation.