Errors, Limits, and Retries
Diagnose failed requests and apply safe retry behavior.
Gateway errors follow the response shape of the client protocol you use. Every business response includes x-request-id; keep it when investigating a failure or contacting support.
Common HTTP statuses
| Status | Meaning |
|---|---|
400 | Invalid request or unsupported parameter |
401 | Missing, invalid, disabled, or expired API key |
402 | Available balance cannot cover the request's maximum possible cost |
404 | Unknown endpoint, model, or task |
413 | Request body is too large |
429 | RPM, TPM, concurrency, or platform rate limit reached |
502–504 | Upstream or platform availability problem |
402 is decided by the request's maximum possible cost (input plus the output allowed by max_tokens), so it can appear before your balance reaches zero. When some balance remains, the error message suggests lowering max_tokens (or your protocol's equivalent output limit); retry with a smaller value to use up the remaining balance.
Check request logs for the stable error code, selected model, status, and timing information. Availability and Service Levels explains how availability is measured and which failures are never billed.
Retry safely
Retry read-only task queries with bounded exponential backoff. Do not automatically retry a model-creation POST when the client cannot tell whether the server accepted it; doing so can create duplicate billable work. Incoming model requests do not support Idempotency-Key.
For streaming calls, preserve already received output and distinguish a clean completion from a disconnected or truncated stream.
Help us improve this page
Found something unclear, outdated, or incorrect?
Last updated on