Home / Docs / Errors

Errors

The error body, and what 401, 402, 403, 413 and 429 mean.

Use this page to read an error answer and decide how to handle it. Errors share one body shape, and the status code tells you which wall you hit.

Read the error body

An error from the OpenAI and responses endpoints has the body {"error": {"message", "type", "code"}}, plus a massrelay object when there is more to say.

{
  "error": {
    "message": "<human-readable text>",
    "type": "<error type>",
    "code": "missing_messages"
  },
  "massrelay": { "param": "messages" }
}

The Anthropic endpoint keeps the type and the message in Anthropic's own error shape and drops the code, so an Anthropic SDK parses it.

Handle each status

• 400 — the request is not usable. invalid_body is a body that is not a JSON object. A missing or empty messages is missing_messages, and the answer names the parameter in massrelay.param.
• 401 — invalid_api_key. One answer for every bad key.
• 402 — out of money. The type is insufficient_quota; the code says which wall: budget_exceeded for a budget envelope, balance_exhausted for an empty wallet, entitlement_exhausted for a plan that does not cover the request. A wall is never silent and a success is never faked.
• 403 — insufficient_scope, or a workspace without an active entitlement for the router.
• 404 — decision_not_found on the explain endpoint.
• 413 — the body is over the limit for the key's plan or the route class.
• 429 — over the request rate. It carries Retry-After.
• 501 — not_ported: an endpoint that authenticates and has no answer yet.