Errors and rate limits
Errors come back with an HTTP status and a stable code. Branch on the code, not the message.
Error format
/v1/chat/completions and /v1/models answer in the OpenAI shape, so SDKs raise their usual exceptions. The type is rate_limit_error for 429, server_error for 5xx and invalid_request_error otherwise.
JSON
{
"error": {
"message": "The authoritative model budget has insufficient remaining capacity.",
"type": "rate_limit_error",
"param": null,
"code": "quota_model_budget_exceeded"
}
}The embeddings, audio and image endpoints use AI Runtime’s envelope instead: {"ok": false, "error": {"code", "requestId", "retryable", "safeMessage"}}, with dotted codes (quota.model_budget_exceeded) and a retryable flag.
Status codes
| Status | Code | What to do |
|---|---|---|
| 400 | validation_invalid_gateway_request | The body or a parameter is invalid; param says which. Fix the request. |
| 401 | authorization_customer_runtime_denied | The key is off, expired or wrong. See Authentication. |
| 404 | not_found_runtime_route | The model id is not on your key. |
| 409 | conflict_idempotency_payload_mismatch | An Idempotency-Key was reused with a different body. |
| 413 | validation_gateway_request_too_large | The body is over 2 MiB. |
| 429 | quota_model_budget_exceeded | Your balance can’t cover the request. Add credit. |
| 429 | quota_runtime_rate_limit_exceeded | Too many requests this minute. Back off and retry. |
| 429 | quota_customer_reservation_exceeded | This one request could cost more than $1. Lower max_tokens or the input. |
| 502 | upstream_model_failed | The provider failed. Retry with backoff. |
| 503 | upstream_domain_unavailable | The model service is briefly unreachable. Retry with backoff. |
Rate limits
- Each model on your key has a requests-per-minute limit. Over it, the API answers 429 with
quota_runtime_rate_limit_exceeded. - The API sends no
Retry-Afterorx-ratelimit-*headers, so retry with exponential backoff and jitter: wait about 1 second, then 2, 4, 8… - Don’t retry 400, 401, 404 or 413, and don’t retry
quota_model_budget_exceeded: add credit first.
Request ids
Every response has x-request-id and x-airuntime-request-id. Send your own x-request-id (8–128 letters, digits, ., _, : or -) and it is kept. Quote it when you write to support.