Errors & limits
Status codes, retries, limits, and troubleshooting.
Read the error envelope
{
"error": {
"message": "A valid organization API key is required.",
"type": "authentication_error",
"param": null,
"code": "invalid_api_key"
}
}Use the HTTP status, error code, and request ID. Provider errors may have additional native fields. We remove provider credentials and account identifiers; do not rely on raw upstream diagnostic text.
Status codes
| Status | Meaning | Action |
|---|---|---|
| 400 | Invalid or unsupported input | Correct the body, model, or unsupported option |
| 401 | Missing, malformed, unknown, or revoked key | Check the organization key in your server environment |
| 402 | Insufficient available credit or spending limit | Add credit or adjust output/key limits |
| 403 | Account hold or permission refusal | Check your organization and contact support |
| 404 / 405 | Unsupported endpoint / wrong method | Use the endpoint map |
| 413 / 415 | Body too large / wrong content type | Keep JSON under 4 MB |
| 429 | Local or upstream rate/concurrency refusal | Back off; inspect Retry-After when present |
| 500 / 502 | Internal or upstream transport failure | Record request IDs; retry carefully |
Limits and retries
The public API accepts JSON bodies up to 4 MB. Model context/output limits also apply, and output ceilings cannot exceed 200,000 tokens. Rate and concurrency controls are per proxy instance; organization balances and monthly key spending limits are enforced transactionally.
Use bounded exponential backoff with jitter for transient failures. The official SDK may retry some statuses automatically; choose its retry and timeout settings deliberately. No gateway retry is automatic, and replayed inference calls are not deduplicated. A timeout after the provider began work can still be billable.
Long-running requests remain subject to hosting and upstream timeouts. Use streaming for progress and handle incomplete or failed terminal events.
A useful diagnostic report
Include the UTC time, endpoint, model, HTTP status, and x-request-id. For provider correlation include x-upstream-request-id when available. Do not share API keys, login codes, or sensitive prompt/response content.
A successful HTTP response with usage_missing in the console is an accounting anomaly, not an exact token measurement. See billing and review behavior.