Errors

Errors use a consistent envelope and a meaningful HTTP status.

{
  "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.

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.

Authentication and key errors

See Authentication. 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.

Getting started

Guides

Decision errors

Authentication and key errors

What to retry

​Decision errors

​Authentication and key errors

​What to retry

Decision errors

Authentication and key errors

What to retry