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_unavailableon 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_unavailableaffects abliterated models only. Standard models keep working. Retrying, or switching to a standard model, is reasonable.insufficient_creditsandspend_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 withkey_suspended.invalid_requestwith 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.