API reference

Errors

Every error has an HTTP status, a stable code, a type, and a request_id. Branch on code. The message can be more specific than the default text below, and can change.

Envelopes

All endpoints except the Anthropic-compatible ones use the OpenAI shape:

{
  "error": {
    "message": "This key may not call this model.",
    "type": "permission_error",
    "code": "model_not_allowed",
    "param": "model",
    "request_id": "req_0PrkfNlKpLQ3dJjbJ6TXska2"
  }
}

param names the request field at fault, or is null.

/v1/messages and /v1/messages/count_tokens use the Anthropic shape, with code added:

{
  "type": "error",
  "error": { "type": "permission_error", "message": "This key may not call this model.", "code": "model_not_allowed" },
  "request_id": "req_0PrkfNlKpLQ3dJjbJ6TXska2"
}

Every error response also has an x-request-id header. Quote it when you contact support.

For errors during a stream, see Streaming.

Error codes

Code HTTP Type Meaning
missing_api_key 401 authentication_error No API key. Send it as Authorization: Bearer <key> (or x-api-key).
invalid_api_key 401 authentication_error The API key is not valid.
key_revoked 401 authentication_error This API key has been revoked.
key_suspended 403 permission_error This API key is suspended. Contact support.
org_suspended 403 permission_error This organization is suspended. Contact support.
ip_not_allowed 403 permission_error Requests from this IP address are not allowed for this key.
model_not_allowed 403 permission_error This key may not call this model.
tier_required 403 permission_error Abliterated checkpoints need a Verified organization. Apply in the dashboard.
feature_not_available 403 permission_error This feature is not enabled for your organization's tier.
model_not_found 404 not_found_error No such model.
not_found 404 not_found_error Not found.
invalid_request 400 invalid_request_error The request is not valid.
context_length_exceeded 400 invalid_request_error The request exceeds this model's context window.
storage_disabled 400 invalid_request_error Response storage is off for this organization (zero retention). Turn it on in Settings, or send store: false.
content_blocked 400 content_policy_error This request falls under a hard limit (child sexual abuse material, or serious uplift for CBRN weapons). It was blocked.
insufficient_credits 402 billing_error Your credit balance is exhausted. Top up in the dashboard.
spend_cap_reached 402 billing_error This key or project has reached its monthly spend cap.
rate_limit_exceeded 429 rate_limit_error Rate limit reached for this key. Retry after the time in the retry-after header.
upstream_error 502 api_error The model backend returned an error.
model_unavailable 503 overloaded_error No healthy capacity for this model right now. Pinned requests are not substituted; retry, or use an auto alias.
safety_unavailable 503 api_error The safety classifier is unavailable, so refusal-free models are paused. Standard models are unaffected.
upstream_timeout 504 api_error The model backend timed out.
internal_error 500 api_error Something went wrong on our side.

Retrying

Retry? Codes What to do
Yes, after a wait rate_limit_exceeded (429) Wait for the retry-after header (seconds), then retry.
Yes, with backoff internal_error (500), upstream_error (502), model_unavailable (503), safety_unavailable (503), upstream_timeout (504) Exponential backoff with jitter, for example 0.5 s, 1 s, 2 s, 4 s, up to a few attempts.
No Every 400, 401, 402, 403 and 404 Fix the request, the key, the balance or the cap first. Retrying returns the same error.

Notes on specific codes:

  • model_unavailable on a pinned model means no deployment of that model has capacity. We never substitute another model for a pinned request. Retry, or use an auto alias, which can fall back within its tier.
  • safety_unavailable affects abliterated models only. Standard models keep working. Retrying, or switching to a standard model, is reasonable.
  • insufficient_credits and spend_cap_reached (402) do not clear on their own within seconds. Top up, raise the cap, or wait for the next month.
  • content_blocked (400) means a hard limit. Do not retry. On the child-safety limit, the key is also suspended, and later calls fail with key_suspended.
  • invalid_request with a message starting "The model rejected the request" comes from the model backend, for example a parameter that model does not support. It is not retried on another model.

Retries and billing

A non-streaming request that returns an error is not billed. A streamed request that fails part-way is billed for what it generated before the failure. So retrying a failed stream can mean paying for some output twice.

The Utmost SDKs retry 429, 500, 502, 503, 504 and network errors automatically, honour retry-after, and never retry 402 or other 4xx errors. The official OpenAI and Anthropic SDKs have similar defaults.