Error Codes

Errors follow the OpenAI shape:

error

{
  "error": {
    "message": "Human-readable summary",
    "type": "error_category",
    "code": "machine_readable_code",
    "param": "field_name_if_applicable"
  }
}

Every error response also carries an X-Request-Id header. Include it when reporting issues to CloudService support. For symptom-first fixes, start from Troubleshooting.

Codes

HTTP	Code	Type	Meaning	What to do
`401`	`invalid_credentials`	authentication_error	The API key is missing, malformed, or revoked.	Check the Authorization header. Get a replacement key if needed.
`403`	`key_expired`	permission_error	The API key was valid but has now expired.	Request a renewed key from CloudService support.
`403`	`key_disabled`	permission_error	The API key is disabled, or the key is scoped to a different provider than the model you requested.	Check that the model matches your key’s provider scope. If it does, contact CloudService support.
`429`	`rate_limit_exceeded`	rate_limit_error	You exceeded the per-key requests-per-minute limit.	Back off and retry with jitter. See Rate Limits for your specific cap.
`429`	`balance_temporarily_reserved`	rate_limit_error	Another in-flight request is temporarily reserving this key’s available balance.	Wait for that request to finish, honor Retry-After, then retry once.
`429`	`limit_reached`	quota_error	You used your full token budget for this period.	Top up the existing key with a compatible token pack before retrying.
`402`	`insufficient_credit`	quota_error	The key does not have enough available credit or tokens to start this request.	Top up the existing key. If another request is still running, wait for it to settle before checking the balance.
`400`	`invalid_request`	invalid_request_error	The request body failed schema validation.	Check the parameter list for the endpoint. Common causes: missing model, empty messages, malformed tool_calls.
`404`	`model_not_found`	invalid_request_error	The model id isn't in the catalog.	Use GET /v1/models for API credit or GET /token/v1/models for API tokens to see the current list.
`400`	`context_length_exceeded`	invalid_request_error	The combined input exceeds the model context window.	Trim conversation history or switch to a model with a larger window.
`502`	`provider_unavailable`	api_error	The model provider is temporarily unavailable for this request.	Retry with exponential backoff, or switch to another available model.
`502`	`upstream_error`	api_error	The upstream provider returned an error or timed out.	Retry with exponential backoff. If persistent, try a different model.
`504`	`upstream_timeout`	api_error	The provider took too long to respond.	Retry. For long generations consider streaming.
`500`	`internal_error`	api_error	Unexpected error inside the gateway.	Retry. If it persists, contact support with the request id from the response headers.

Retry behavior

For a retryable 429, honor the Retry-After header. Do not create parallel retries. The caps and headers behind a 429 are described in Rate limits.
5xx responses are safe to retry with capped exponential backoff and jitter. Stop retrying after response content has started streaming.
Most 4xx responses are not retryable. The explicit exception is a temporary 429. Authentication, permission, validation, and exhausted-quota errors require corrective action first.