Errors

Every status code the platform returns, what causes it, and what to do about it.

The shape of an error

Chat, audio and every other model-shaped endpoint fail with the same envelope, checked directly against this deployment:

JSON
{
  "error": {
    "message": "human-readable, safe to show as-is",
    "type": "invalid_request_error",
    "param": "messages",
    "code": "400"
  }
}
Three shapes, not one
Model endpoints (chat, embeddings, audio) use the envelope above. The tool endpoints — PDF, the sandboxed interpreter, vector stores, files, skills, MCP and /v1/route — go through a second gateway layer that answers its own failures as {"error": {"code": "invalid_api_key", "message": "…"}} with a string code (invalid_api_key, not_found, bad_path, payload_too_large, upstream_unreachable). When the service behind it answers, its body is passed through unchanged, and that service is a plain FastAPI app, so its errors look like {"detail": "message"}; a mistyped path is {"detail": "Not Found"}. Read error.message first and fall back to detail rather than assuming one shape everywhere.

Reference

StatusWhenDo this
⁦400 Bad Request⁩Malformed JSON; a missing required field (messages); a model id that does not exist; for /v1/pdf, HTML with a remote reference.Fix the request. Call GET /v1/models if the model id is in question — see Models.
⁦401 Unauthorized⁩No Authorization header; a key that does not exist or was revoked; or a key LiteLLM has blocked because your organisation's balance is exhausted or its monthly cap was reached.Check the key, then check the balance in the console's Billing page — see Billing.
⁦404 Not Found⁩A path that does not exist.Check the path against the endpoint shown on each doc page.
⁦405 Method Not Allowed⁩The right path, the wrong verb — e.g. GET on /v1/chat/completions.Check the Allow header on the response for the accepted verbs.
⁦413 Payload Too Large⁩The request body is over the size limit for that path — a large image, audio file or PDF.Shrink or split the input. Limits per path are in Rate limits.
⁦429 Too Many Requests⁩An IP address over its edge budget, or a key over its rpm/tpm — see Rate limits.Read retry-after and back off with jitter. Safe to retry.
⁦500 Internal Server Error⁩A backend failed on your specific input — a corrupt upload, an edge case in audio decoding.Retry once. If it repeats with the same input, that input is the cause — change it rather than retrying again.
⁦502 Bad Gateway⁩The router could not reach the backend a request was classified to, or that backend errored answering it.Retry with backoff — see Rate limits for the same helper.
403 is used by the console's own management API for role checks inside an organisation ("requires admin role") — it has not been observed from /v1 itself, which either accepts your key or answers 401.

Reading one

curl -s https://api.data.larsima.com/v1/chat/completions \
  -H "Authorization: Bearer $DATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "not-a-model", "messages": []}' \
  | jq -r '.error.message // .detail'
↑↓ Navigate ↵ Open esc Close