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.

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-Afteror 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.