Errors and retries

Diagnose failures using HTTP status, error bodies, and request logs.

Start with three sources

Record the HTTP status, message / type / code in the error body, and the request time, model ID, and response request identifier if supplied. Use these to find console request logs. Remove keys, cookies, and sensitive input before sharing diagnostics.

A typical OpenAI-compatible error looks like this. Gateways, upstream services, and reverse proxies can return different structures, plain text, or HTML:

{
  "error": {
    "message": "Example error message",
    "type": "invalid_request_error",
    "param": null,
    "code": null
  }
}

Symptom	Next action
400	Check JSON, required fields, model capabilities, and parameter combinations; correct the request first
401 / 403	Check the key, account status, model permissions, and access restrictions; do not retry blindly
404 / HTML	Verify the hostname, path prefix, endpoint, and resource ID
429	Distinguish frequency, concurrency, and quota restrictions from the error and logs; avoid unbounded retries
500 / 502 / 503 / 504	Check gateway and upstream status and whether execution already occurred before retrying
Disconnection / timeout	Check the network and timeout settings; local cancellation does not prove no server execution
HTTP 200 without a model list	Check success: false and message; model-list lookup failures may currently return 200
HTTP 200 with unfinished output	Inspect Responses status, Chat finish_reason, and SSE terminal events

Status codes can vary by upstream and deployment configuration. HTTP 200 alone does not prove application-level completion.

Bound your retries

The SDK examples disable retries. Production retry policies should cap both attempts and total time and use exponential backoff with jitter. Honor Retry-After when provided. Fix permission and parameter errors first; resolve account quota problems before retrying.

Generation requests are not inherently idempotent. This specification does not promise Idempotency-Key support. Retrying after a timeout, interrupted stream, or 5xx may duplicate output or usage; inspect logs and application state first. Do not silently restart a generation after delivering partial text.

Unavailable models

List models again with the same key, then check the exact model ID, protocol, group, and channel configuration. Avoid masking the problem by switching models arbitrarily; capabilities and pricing may differ.

API coverage · Production integration · Troubleshooting

简体中文

Model routing · Rate limits · Observability · AI SDK