Skip to content

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 Anthropic PermissionDeniedError, and so on).
  • x-vidai-error-code carries the gateway's code, the same in every format. Match on it.
  • x-vidai-request-id is the id to quote and to find the call in Request logs.
  • x-vidai-error-detail says 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.

A refused call in Request logs: the outcome, what refused it and why, and the rules weighed