API
Errors
Status codes, the error body and which errors to retry.
Errors come back as JSON with an error object, in OpenAI's shape. The status code tells you what to do next.
Status codes
| Code | Meaning | Retry |
|---|---|---|
| 400 | Bad request: the body isn't valid JSON or a field is wrong. unsupported_paid_feature means a server tool such as web search, which AZRouter doesn't offer. | No |
| 401 | Missing, malformed or revoked key, or a key switched off because it reached its own spending limit or your tier's monthly cap. | After you fix the key or the cap resets |
| 402 | insufficient_user_quota: your credit balance has run out. | After a top-up |
| 403 | "This token has no access to model …": the slug is misspelled or not on sale. Check GET /v1/models. | No |
| 429 | rate_limit_exceeded: a rate limit was hit, yours or the upstream provider's. | After Retry-After |
| 500, 502, 503 | service_unavailable: no upstream can serve the request right now, or the gateway failed. | With backoff |
Error body
A key that doesn't exist:
curl https://api.azrouter.dev/v1/chat/completions \
-H "Authorization: Bearer sk-not-a-real-key" \
-H "Content-Type: application/json" \
-d '{"model": "qwen/qwen3.8-flash", "messages": [{"role": "user", "content": "Hello"}]}'{"error":{"code":"","message":"Invalid token (request id: ...)","type":"new_api_error"}}A body that isn't JSON:
curl https://api.azrouter.dev/v1/chat/completions \
-H "Authorization: Bearer $AZROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{not json'{"error":{"code":"","message":"Invalid request: Invalid request: invalid JSON request body (request id: ...)","type":"new_api_error"}}Errors from 402, 429 and 5xx use a fixed message and carry a request_id. Quote it when you contact support:
{"error":{"message":"The service is temporarily unavailable. Please retry.","type":"server_error","param":null,"code":"service_unavailable"},"request_id":"..."}Retries
Retry 429 after the Retry-After header, and 5xx with exponential backoff. A 400, 401, 402 or 403 fails again until you change the request, the key or your balance. The OpenAI SDKs already retry 429 and 5xx for you; see Rate limits.