Skip to main content
When a request fails, check the HTTP status code and the error object in the response body. Use error.type together with error.code (when present) and the status code to decide what to do next. If you need help, contact support and include the response request_id and traceId.

​
Error response format

Most failed non-streaming requests return JSON like this:
On 429 responses you may also see Retry-After and X-RateLimit-* headers. Some errors also return param to identify the related request field. Retryable errors, such as rate limits, can also return retry_after_sec to indicate how long to wait before retrying. Error responses include a request_id for troubleshooting. It may appear in error.message, error.request_id, and the request-id or x-request-id response headers. When contacting support, provide the request_id and retain the traceId, request time, model ID, and API path.

​
Error reference

Read message for specifics — limits, model names, parameters, or which API to use.

​
Quick guide

  • Fix first, then retry: authentication_error, billing_denied, model_not_found, invalid_request, unsupported_protocol
  • Wait, then retry: rate_limit_error — use retry_after_sec or Retry-After when available
  • Retry with backoff: service_unavailable and in-stream streaming errors; contact support with request_id and traceId if the issue persists
  • Usually do not retry: client_aborted; if the request reached a model, billing may still apply
  • If code is missing: rely on error.type and the HTTP status
  • Still stuck? Contact support with request_id and traceId

​
Streaming requests

When a streaming request fails (e.g. stream: true), how the error is returned depends on when the failure happens:
  1. Before any stream data is sent — You get the same JSON error object and a non-2xx HTTP status as in the table above.
  2. After the stream has started — HTTP may already be 200. The failure is reported as an error event inside the stream (format depends on the API). The text is usually generic, for example upstream stream error, please retry later. Retry with backoff; if it keeps happening, contact support with request_id and traceId.