Guides
Errors
Errors include a machine-readable code and a message. Distinguish a rejected request from an uncertain result that may already have used provider capacity.
Error format
{
"error": {
"message": "Insufficient available credit for this request. Add credit or resolve pending reservations.",
"type": "invalid_request_error",
"code": "insufficient_credit"
}
}Use the response's x-request-id and your activity records to investigate a request. Never include the secret key or conversation content in a support report.
Status codes
| Status | Meaning / action |
|---|---|
| 400 | Invalid body, unknown fields, context limit, or unsupported capability. |
| 401 | Missing, invalid, or revoked Bearer key. |
| 402 | Insufficient available credit or the API key's spending limit was reached. |
| 403 | Unavailable account or a model outside the key's allowlist. |
| 404 | Unknown endpoint or unapproved model ID. |
| 409 | An idempotency reference was already used. |
| 413 / 415 | Body too large or content type other than application/json. |
| 429 | Rate, request, or concurrency limit. Wait for the Retry-After interval before retrying; pending reservations may require reconciliation. |
| 502 | Provider failure, invalid stream, or usage unavailable. |
| 503 | Maintenance, provider readiness, or launch configuration. |
Uncertain results
An upstream timeout or usage_unavailable response can leave a pending hold. These errors include X-Should-Retry: false to suppress automatic SDK replays. Provider failure codes distinguish unavailable models, invalid parameters, authentication, quota and throttling without returning private provider details. Inspect activity and reconcile the first result before deciding to submit a new call.
Idempotency
An optional Idempotency-Key contains 1–128 letters, digits, dots, underscores, colons, or hyphens. Reusing a reference returns 409 and does not rerun inference. This is duplicate prevention, not cached response replay.