Skip to content

Headers and errors in your client

Every answer says what the gateway did (which model answered, whether a fallback stepped in, what translation changed) and every refusal says why, with a code that never changes. This page is the short version every integration page links to; the full lists are in the reference.

Headers on every answer

Header When Meaning
x-vidai-request-id On every answer and almost every refusal The call's reference: quote it, or paste it into Request logs › Request reference
x-vidai-model An answer a model produced The model that answered
x-vidai-requested-model A different model answered The model you asked for
x-vidai-routing-rule A routing rule applied The rule's id
x-vidai-provider-key The provider has more than one key Its label, never the secret
x-vidai-fallback, x-vidai-fallback-from A fallback model answered true, and the provider it moved from
x-vidai-fallback-attempts More than one attempt Attempts in all
x-vidai-adapted Translation changed or dropped something A list, for example seed,top_k
x-vidai-translation-profile An answer from a provider default or preserve
x-vidai-pseudonymised Personal data was replaced on the way out and put back in the answer 1
x-vidai-token-count The gateway counted tokens itself estimated or tokenizer-match
x-request-id The provider sent one The provider's own id, passed through

Cost is never in the answer: the call is in Request logs within seconds, and Cost totals and dashboards count it within about two minutes.

Request logs with one call found by its request reference and open beside the list: the model asked for and the one that answered, the key, the path and the cost

Reading them from your client

Client How
OpenAI SDK with_raw_response (Python), .withResponse() (TypeScript)
Anthropic SDK with_raw_response (Python), .withResponse() (TypeScript)
Google GenAI SDK response.sdk_http_response.headers (Python)
AI SDK by Vercel result.response.headers
curl curl -i
Apps with no code (IDEs, chat interfaces, low-code tools) They don't show headers: find the call in Request logs, by Key, Model or Path

Refusals

Every refusal from the gateway carries x-vidai-error-code (the same in every format: match on it), x-vidai-stage, x-vidai-error-detail (words) and x-vidai-request-id. The body is in your client's own format, so the SDK raises its usual error.

Status Codes What to do
400 bad_request, provider_override_not_allowed Fix the request; for an endpoint another provider doesn't serve, use a model of the right kind
401 missing_api_key, invalid_api_key, conflicting_auth_headers Check the key (a revoked or expired key is no longer known: issue a new one), and send it in one header only
403 api_key_disabled The key is turned off (suspended, its agent suspended, a budget reached); error.reason may say why (for example agent_suspended)
403 model_not_allowed, denied_by_routing_rule Use a model your key may call (GET /v1/models)
403 content_guardrail_blocked A guardrail blocked the content
404 model_not_found, endpoint_not_found Check the model name or the path
413 payload_too_large Send less
429 rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded Back off and retry
500 guardrail_check_failed, internal_error Retry; quote the request id if it persists
502, 504 upstream_unreachable, upstream_closed, upstream_timeout The provider didn't answer; retry
503 ai_traffic_suspended, fallback_exhausted, provider_disabled, routing_target_unavailable, rate_limit_unavailable AI traffic is stopped, or nothing could serve the model

A provider's own error is passed through in your format with x-vidai-error-code: upstream_provider_error.

Good to know

  • The gateway's own 429 carries no Retry-After or rate-limit headers; back off on your side.
  • A fallback chain may already have tried another model before the first byte. Keep your client's own retries few and spaced out, so a failure isn't multiplied (Fallback and retries).
  • The full lists: Response headers and Errors.