Errors¶
The promise: every code below is stable. A code is never renamed or removed; new codes may be added. Match on
x-vidai-error-code, and treat a code you don't know by its HTTP status. For what to do in practice, see
Errors and refusals.
The body, in your SDK's format¶
Every error is an HTTP error status with a body in the format you called in, so your SDK raises its usual error.
| You called in | Body | Where the code is |
|---|---|---|
OpenAI (/v1/…) |
{"error": {"message": "…", "type": "…", "code": "<code>", "param": null}} |
error.code, and the header |
Anthropic (/v1/messages) |
{"type": "error", "error": {"type": "…", "message": "…"}} |
The x-vidai-error-code header |
Gemini (/v1beta/…) |
{"error": {"code": <status>, "message": "…", "status": "…"}} |
The x-vidai-error-code header |
| Azure OpenAI | {"error": {"code": "<code>", "message": "…"}} |
error.code, and the header |
| Bedrock | {"message": "…", "__type": "com.amazon.coral.service#<Exception>"} |
The x-vidai-error-code header (and x-amzn-errortype) |
type and status use each format's own words (authentication_error, UNAUTHENTICATED, …), so the SDK maps them
to its usual classes. Every gateway error also carries x-vidai-stage, x-vidai-error-detail, x-vidai-source,
x-vidaiserver-version and x-vidai-request-id (Response headers).
Refused by the gateway¶
Nothing was sent to a provider.
| Code | Status | Stage | Meaning | What to do |
|---|---|---|---|---|
missing_api_key |
401 | auth |
No key was sent | Send one in Authorization: Bearer, x-api-key or x-goog-api-key |
invalid_api_key |
401 | auth |
The key isn't recognised (wrong, revoked or expired) | Check the key |
conflicting_auth_headers |
401 | auth |
Two headers carry different keys | Send one |
api_key_disabled |
403 | auth |
The key is turned off. error.reason may say why (below) |
Don't retry; ask whoever looks after the key |
admin_key_not_allowed |
403 | auth |
A key for managing the gateway was used to call a model | Use a key issued in the Control room |
model_not_allowed |
403 | auth |
The key may not call this model | Use an allowed model, or ask for this one |
batch_file_unverified |
403 | auth |
A key limited to some models made a batch whose input file couldn't be checked | Upload the file through the gateway |
ai_traffic_suspended |
503 | auth |
An admin stopped all AI traffic | Don't retry until it's resumed |
denied_by_routing_rule |
403 | routing |
A rule denies this model (or the one a rule would send it to) for this key; the message is the rule's reason. The OpenAI body adds rule_id, rule_name and model |
Use another model, or ask an admin |
model_not_found |
404 | routing |
No model of that name | Check the name against GET /v1/models |
endpoint_not_found |
404 | routing |
The gateway doesn't serve this path | Check the path (Endpoints) |
provider_override_not_allowed |
400 | routing |
x-provider names a provider that doesn't serve the model |
Drop the header, or name the model's own provider |
provider_disabled |
503 | routing |
The model's provider is switched off | Don't retry until it's switched on |
routing_target_unavailable |
503 | routing |
A rule set to refuse matched, and its target is switched off or removed | Don't retry until an admin acts |
fallback_exhausted |
503 | routing |
The provider is unavailable, every entry of the fallback chain was skipped, and the chain is set to refuse. The OpenAI body adds fallback_config_id and model |
Retry later |
rate_limit_exceeded |
429 | rate_limit |
The key's requests a minute are used up | Retry after a pause |
token_limit_exceeded |
429 | rate_limit |
A tokens-a-minute limit | Retry after a pause, or send less |
concurrency_limit_exceeded |
429 | rate_limit |
Too many calls at once | Retry when one finishes |
rate_limit_unavailable |
503 | rate_limit |
The key has a limit, the shared count can't be read, and the gateway is set to refuse rather than let calls through uncounted. An outage, not your limit | Retry shortly |
bad_request |
400 | request_validation or routing |
The request is malformed, or can't be served as sent (for example, an endpoint sent to a provider of another format); the message says what | Fix the request |
payload_too_large |
413 | routing or guardrail |
The request body is over the size limit | Send less |
content_guardrail_blocked |
403 | guardrail |
A guardrail blocked the request | Change the content |
guardrail_check_failed |
500 | guardrail |
The guardrail check itself failed | Retry; tell an admin if it persists |
configuration_unreadable |
503 | routing |
A stored secret the call needs (such as a provider's key) can't be read by the gateway | Tell an admin: it's a configuration fault, not your request |
telemetry_unavailable |
503 | telemetry |
The gateway can't record calls right now and is set to refuse rather than let calls through unrecorded | Retry shortly |
internal_error |
500 | internal |
An unexpected error in the gateway | Retry; tell an admin if it persists |
Vidai sets rate limits in requests a minute, so rate_limit_exceeded is the 429 you'll meet. The other two 429 codes
belong to the stable set; code that handles every 429 alike covers them.
error.reason on a turned-off key¶
Beside api_key_disabled, the body may carry error.reason: a short code set by whoever, or whatever, turned the key
off. Examples: agent_suspended, budget_exceeded, manual. The list is open: log it and show it, but don't fail
on a value you don't know.
At or after the provider¶
| Code | Status | Stage | Meaning | What to do |
|---|---|---|---|---|
upstream_unreachable |
502 | upstream |
The provider couldn't be reached | Retry later |
upstream_timeout |
504 | upstream |
The provider didn't answer in time | Retry, perhaps with a smaller request |
upstream_closed |
502 | upstream |
The provider dropped the connection, or sent an answer that couldn't be read | Retry |
upstream_provider_error |
The provider's | upstream |
The provider answered with an error; the message is the provider's | Depends on the provider's error |
A provider's error reaches you with its own status and message: as sent, if you called in the provider's format, or rewritten into your format if not.
Only in Request logs¶
| Code | Meaning |
|---|---|
client_disconnected |
Your program closed the connection before the answer. Nothing was sent back, so you never see it; the call's record in Request logs does |
What's never in an error¶
- A provider's address. An error names a provider by the name your organisation gave it, never its host or URL.
- A secret. Keys are never echoed. In Request logs they show by their start only.
Codes that don't exist¶
Older documentation listed codes the gateway never sends. If your code matches on these, change it:
| Never sent | Match on instead |
|---|---|
key_not_found |
invalid_api_key |
key_disabled |
api_key_disabled |
rate_limited |
rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded |
routing_denied |
denied_by_routing_rule |
upstream_unavailable |
upstream_unreachable, upstream_timeout, upstream_closed |