Skip to content

Usage

Errors and retries

Error format, common codes, and retry strategy.

Errors return a JSON body with a type, code, and human-readable message.

json
{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Too many requests. Retry after the period in the Retry-After header.",
    "request_id": "req_demo_02"
  }
}

Common status codes

StatusMeaningRetry?
400Invalid requestNo — fix the request
401Missing or invalid keyNo
404Unknown model IDNo
429Rate limitedYes, with backoff
5xxUpstream or server errorYes, with backoff

Retry strategy

  1. Retry only on 429 and 5xx responses.
  2. Use exponential backoff with jitter.
  3. Cap total attempts.
  4. Log the request ID for support.