AI Gateway errors and limits
AI Gateway returns OpenAI-compatible errors with an error object containing message, type, param, and code. Inspect the HTTP status and error code before retrying.
Error responses
| Status | Meaning | Action |
|---|---|---|
400 | Invalid or unsupported request. | Check the model, parameters, input types, and error message. Decision API validation can return upstream_rejected_request. |
401 | Missing, invalid, or revoked key. | Check the bearer key and replace revoked credentials. |
402 | insufficient_quota. | Check remaining included usage and pay-as-you-go settings. |
403 | Key lacks permission. | Confirm AI Gateway access and the key’s product scope. |
404 | Unknown model or unavailable feature. | List available models and confirm account access. |
413 | Request or state exceeds a size limit. | Reduce the JSON body, or the decision API state to within the model’s limit. |
429 | Gateway or provider rate limit. | Honor Retry-After when present and reduce concurrency. |
500 | Internal error. | Retry with bounded backoff; contact support if it persists. |
502 | Model provider failure. | Retry transient failures with bounded backoff. |
503 | Service overloaded or provider unavailable. | Retry later; contact support for persistent failures. |
504 | Model request timed out. | Reduce the workload and retry cautiously. |
A retry sends a new request and can incur another charge. Do not automatically retry invalid requests, authentication errors, or exhausted quota. Use bounded exponential backoff with jitter for transient failures.
Request limits
See the API reference(opens in a new tab) for rate, request size, and input limits. Test keys have separate rate and spend controls. Context and output limits vary by model.
Streaming failures
After an SSE response starts, errors can arrive within the stream. Handle failure events and missing completion events even if the initial HTTP status was successful. Preserve the request ID for diagnosis.
Get help
Send the request ID, endpoint, model alias, status, error code, and timestamp with time zone to support(opens in a new tab). For decision API requests, include x-typesafe-request-id. Do not send API keys or sensitive prompt content. For account enablement or commercial requirements, contact sales.