Errors and refusals¶
Purpose: when the gateway refuses a call, your program learns why, in a form it can act on: your SDK raises its usual error, and one header carries a stable code that's the same in every format. Rules are applied before a call reaches a model, so a refusal costs nothing and nothing was sent.
How an error reaches you¶
- The body is in your SDK's own format, so the SDK raises its normal error class (an OpenAI
AuthenticationError, an AnthropicPermissionDeniedError, and so on). x-vidai-error-codecarries the gateway's code, the same in every format. Match on it.x-vidai-request-idis the id to quote and to find the call in Request logs.x-vidai-error-detailsays why in words (up to 512 characters), for your logs.
The same wrong key, in three formats:
OpenAI 401 {"error":{"code":"invalid_api_key","message":"…","param":null,"type":"authentication_error"}}
Anthropic 401 {"type":"error","error":{"type":"authentication_error","message":"…"}}
Gemini 401 {"error":{"code":401,"message":"…","status":"UNAUTHENTICATED"}}
x-vidai-error-code: invalid_api_key
x-vidai-stage: auth
Codes are stable: never renamed or removed. New ones may be added, so treat an unknown code by its HTTP status.
Every refusal, and what to do¶
| What happened | Status and code | What to do |
|---|---|---|
| No key sent | 401 missing_api_key |
Send the key in Authorization: Bearer, x-api-key or x-goog-api-key |
| The key isn't recognised (mistyped, revoked, expired, or an API token sent by mistake) | 401 invalid_api_key |
Check the key; issue a new one if it was revoked |
| Two headers carry different keys | 401 conflicting_auth_headers |
Send one key |
| The key is turned off: suspended, its agent suspended, its person left the team, a budget reached, unused too long | 403 api_key_disabled |
Don't retry. Read error.reason (below), then ask whoever looks after the key |
| The model isn't allowed for this key, including a model outside the region its team, agent, application or environment keeps calls in, or a rule's target the key may not use | 403 model_not_allowed |
Use a model from GET /v1/models (it lists only what the key may call), or ask for this one to be added |
| A rule denies it: a routing rule refuses this model for this key; its reason is the message | 403 denied_by_routing_rule |
Use another model, or ask an admin. The OpenAI body adds rule_id, rule_name and model |
| Content blocked by a guardrail | 403 content_guardrail_blocked |
Change the content; don't resend it unchanged |
| Rate limited: the key's requests a minute are used up | 429 rate_limit_exceeded |
Wait, then retry with backoff (the minute starts again) |
| Traffic stopped: an admin stopped all AI traffic | 503 ai_traffic_suspended |
Don't retry until it's resumed |
| The model's provider is switched off | 503 provider_disabled |
Don't retry until an admin switches it on |
| A rule's target is switched off, and the rule is set to refuse | 503 routing_target_unavailable |
Don't retry until an admin changes it |
| Every model in the fallback chain is unavailable, and the chain is set to refuse | 503 fallback_exhausted |
Retry later |
| No model of that name | 404 model_not_found |
Check the name against GET /v1/models |
| The path isn't one the gateway serves | 404 endpoint_not_found |
Check the path (Endpoints) |
| The request can't be served as sent (for example, an endpoint sent to a provider of another format) | 400 bad_request |
Read the message; fix the request |
| Request too large | 413 payload_too_large |
Send less |
| The provider couldn't be reached, timed out, or dropped the connection | 502 upstream_unreachable, 504 upstream_timeout, 502 upstream_closed |
Retry later |
| The provider answered with an error | the provider's status, upstream_provider_error |
Read the provider's message, in your format |
Every code, with its stage, is in the errors reference.
Why a key is turned off: error.reason¶
Beside api_key_disabled, the body may carry a short reason code in error.reason, set by whoever turned the key off.
Examples: agent_suspended, budget_exceeded, manual. The list is open: log it, show it, and don't fail on a value
you don't know.
Match on the code¶
import openai
try:
reply = client.chat.completions.create(model="gpt-4o", messages=messages)
except openai.APIStatusError as err:
code = err.response.headers.get("x-vidai-error-code")
request_id = err.response.headers.get("x-vidai-request-id")
if code == "rate_limit_exceeded":
... # back off and retry
elif code in ("api_key_disabled", "model_not_allowed", "denied_by_routing_rule"):
... # don't retry: tell someone, quoting request_id
elif code == "content_guardrail_blocked":
... # ask the user to change what they sent
else:
raise
import OpenAI from "openai";
try {
const reply = await client.chat.completions.create({ model: "gpt-4o", messages });
} catch (err) {
if (!(err instanceof OpenAI.APIError)) throw err;
const code = err.headers?.get("x-vidai-error-code");
const requestId = err.headers?.get("x-vidai-request-id");
switch (code) {
case "rate_limit_exceeded":
/* back off and retry */ break;
case "api_key_disabled":
case "model_not_allowed":
case "denied_by_routing_rule":
/* don't retry: tell someone, quoting requestId */ break;
default:
throw err;
}
}
curl -sS -D - "$VIDAI_GATEWAY/v1/chat/completions" \
-H "Authorization: Bearer vk_not_a_real_key" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hi"}]}' \
| grep -i -E '^(HTTP|x-vidai-)'
The Anthropic SDKs raise anthropic.APIStatusError with the same response.headers; the Google Gen AI SDK raises
errors.APIError. With an Anthropic or Gemini client the code is only in the header, so read it there.
Retry only what's worth retrying¶
| Retry with backoff | Don't retry |
|---|---|
rate_limit_exceeded, upstream_unreachable, upstream_timeout, upstream_closed, rate_limit_unavailable, telemetry_unavailable, guardrail_check_failed, internal_error, fallback_exhausted |
Every 401 and 403; model_not_found, endpoint_not_found, bad_request, payload_too_large; ai_traffic_suspended, provider_disabled, routing_target_unavailable (until someone acts) |
Your organisation may already have the gateway try the next model when a provider fails, before you see anything (Migrate from calling providers directly). Keep your own retries few and spaced out, so the two don't multiply.
See it from the other side¶
Every refusal is a call in Daily › Request logs, with the same words: who called, what refused it (a budget, a
rule, a guardrail, the key), and why. Find it by its x-vidai-request-id in Request reference, or filter by
Why it failed. Request ids and Request logs shows how.

Related¶
- Errors reference: every code, its status and stage
- Limits
- Keys and API tokens