Errors

Branch on the HTTP status and code, never on the message text. Every error carries a request ID (req_…); include it when you contact support.

Shapes

Inference endpoints use the native shape of their API, so SDK error classes work:

{
  "error": {
    "message": "Rate limit reached for requests on this key (60 per minute). Retry after 2s.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limited",
    "request_id": "req_0193a6c2f0017aa4b2c1d0e9f8a7b6c5"
  }
}

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit reached for requests on this key (60 per minute). Retry after 2s.",
    "code": "rate_limited"
  },
  "request_id": "req_0193a6c2f0017aa4b2c1d0e9f8a7b6c5"
}

Policy and Admin APIs use RFC 9457 problem details (application/problem+json):

{
  "type": "https://docs.antarah.dev/errors/policy_revision_conflict",
  "title": "Policy revision conflict",
  "status": 409,
  "detail": "The policy changed after revision 3. Retrieve it and retry with revision 4.",
  "instance": "/v1/organization/policies/pol_0193a6c2e7b47c3d9f1e2a4b5c6d7e8f",
  "code": "policy_revision_conflict",
  "request_id": "req_0193a6c2f0017aa4b2c1d0e9f8a7b6c5",
  "param": "revision"
}

type links to the code’s page here. Validation errors (422 validation_error) add errors[], each with a JSON pointer and detail. Errors after a stream has started end the stream with a terminal event instead; see Streaming.

Retries

Every error response has x-should-retry: true or false, which the OpenAI and Anthropic SDKs follow.

Retry	Codes
After `Retry-After`	`429 rate_limited`, `503 upstream_unavailable`, `503 credit_balance_unavailable`, `409 idempotency_in_progress`
With backoff	`500 internal_error`, `502 upstream_error`, `503 service_unavailable`, `503 policy_evaluation_unavailable`, `504 upstream_timeout`
After you fix something	`402` (add credits, raise a limit), `401 session_expired` (sign in again), `409 policy_revision_conflict` (re-read)
Never unchanged	Every other `4xx`

Model runtime errors are never passed through as they are: their messages can name internal systems. A request the runtime rejects becomes 400 upstream_invalid_request; runtime failures become 502, 503, or 504. Each code has its own page in this tab, with what it means and what to do.

Overview

400 Bad request

401 Unauthorized

402 Payment required

403 Forbidden

404 Not found

409 Conflict

410 Gone

413 Payload too large

415 Unsupported media type

422 Unprocessable

429 Too many requests

5xx Server errors

Shapes

Retries

​Shapes

​Retries

Shapes

Retries