Skip to content

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