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

# Errors

> Error format, codes, and what is safe to retry.

Errors use a consistent envelope and a meaningful HTTP status.

```json theme={null}
{
  "error": {
    "code": "model_not_found",
    "message": "Unknown model. Choose 'tazo-large' or 'tazo-small'.",
    "retryable": false
  }
}
```

Branch on `code`, not on `message`. `retryable` tells you whether repeating the
same request can succeed.

> [!NOTE]
>
> Request validation on the API key endpoints can return FastAPI's default `422`
> body, `{"detail": [...]}`, instead of this envelope. Decision validation
> errors use the envelope.

## Decision errors

| Status | Code | Retryable | Meaning |
| - | - | - | - |
| 400 | `invalid_idempotency_key` | No | The key is blank or longer than 256 characters. |
| 404 | `model_not_found` | No | Unknown model. |
| 409 | `idempotency_conflict` | No | The key was used with a different request. |
| 413 | `audio_too_large` | No | Audio is over 16 MB. |
| 413 | `request_too_large` | No | The request is too large to persist. |
| 422 | `invalid_request` | No | The `request` JSON does not match the v1 contract. |
| 4xx | `model_rejected_request` | No | The model rejected the request, for example it exceeds its capabilities. |
| 502 | `runtime_contract_violation` | Yes | The model returned an invalid response. |
| 502 | `model_runtime_error` | Yes | The model could not complete the request. |
| 503 | `tazo_unavailable` | Yes | The inference service is unavailable. |
| 503 | `durable_execution_unavailable` | Only with a key | Submission could not be confirmed. |
| 504 | `tazo_timeout` | Yes | The inference service timed out. |
| 504 | `decision_pending` | Only with a key | Still processing. See [Idempotency](/guides/idempotency.md). |

## Authentication and key errors

See [Authentication](/authentication.md#authentication-errors). Key management adds:

| Status | Code | Meaning |
| - | - | - |
| 404 | `api_key_not_found` | The key does not exist, or belongs to another account. Both look the same. |

Management endpoints never recommend automatic retries, since a timed-out
creation may already have committed.

## What to retry

* Retry `retryable: true` errors with backoff.
* On decisions, always reuse the same `Idempotency-Key` across attempts.
* Do not retry `4xx` errors without changing the request.
* Never blindly retry `POST /v1/api-keys`. List your keys first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.