Errors

Error shape

The gateway follows the OpenAI-compatible error shape. Check the HTTP status first, then read error.message and error.code before deciding whether to retry.

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}

Common statuses

401 means the API key is missing, invalid, or has been deleted. Create a new key in the console and keep it on the server side.

403 means the key or account cannot use the requested model. Check the model ID returned by GET /v1/models or contact support.

429 means the request was rate-limited or the account has insufficient available balance. Slow down, retry with backoff, or check the wallet.

5xx means the gateway or an upstream provider failed. Retry idempotent requests with exponential backoff and keep the response body for troubleshooting.

Retry guidance

Do not blindly retry 400, 401, or 403 responses. For 429 and transient 5xx responses, use bounded exponential backoff with jitter. Generation requests may have provider-specific behavior, so verify the final response before submitting a duplicate job.