Errors
Error responses return a JSON body with a single error field containing the message as a string. The HTTP status code carries the semantic meaning.
error.json
{
#60a5fa]">class="text-emerald-400">"error": class="text-emerald-400">"Insufficient funds. Please top up your balance."
}Status codes
| Code | Meaning | What to do |
|---|---|---|
| 400 | Bad request — missing model, missing messages, invalid JSON, or upstream rejected the request | Check the error message and fix your payload |
| 401 | Missing Authorization header or invalid API key | Verify the key is set and active in your dashboard |
| 402 | Insufficient balance or per-key spending cap reached | Top up balance or raise the per-key cap |
| 405 | Method not allowed (endpoint expects POST or GET only) | Check the HTTP method for the endpoint |
| 413 | Request body exceeds 500 KB | Trim the messages or shorten the prompt |
| 429 | Rate limit exceeded (60 req/min) | Back off and retry after the Retry-After header |
| 500 | Internal server error | Retry with exponential backoff; contact support if persistent |
| 502 | Upstream provider returned an error | Retry; the provider may be having an outage |
| 503 | Upstream API not configured or unavailable | Contact support |
| 504 | Request timed out after 60 seconds | Retry; consider a shorter prompt or lower max_tokens |
Retry strategy: for 429, 500, 502, 503, and 504, retry with exponential backoff (start at 1s, double up to 30s, max 5 attempts). Do not retry 400, 401, 402, 405, or 413 — those are client errors.