Response headers¶
What the gateway adds to an answer. All are informational: a client that ignores them works the same.
On answers¶
| Header | When | Value and meaning |
|---|---|---|
x-vidai-request-id |
On every answer and almost every refusal | The gateway's id for the call. Quote it; find the call by it in Request logs (Request ids) |
x-request-id |
When the provider sends one | The provider's id for the call, passed through. Not Vidai's |
x-vidai-model |
Every answer a model produced, streams and provider errors included; not on the gateway's own refusals | The model that answered, after aliases, routing and fallback |
x-vidai-requested-model |
When it differs from x-vidai-model |
The model you asked for |
x-vidai-routing-rule |
When a routing rule decided where the call went | The rule's id |
x-vidai-provider-key |
When the provider has more than one key | The provider key's label, never its secret: which of the provider's keys served the call |
x-vidai-fallback |
When a fallback chain sent the call on because its first choice was unavailable | true |
x-vidai-fallback-from |
With x-vidai-fallback |
The provider the call would have gone to |
x-vidai-fallback-attempts |
When more than one attempt was made (a chain set to try the next model) | The number of attempts, the one that answered included. A provider may charge for a failed attempt |
x-vidai-translation-profile |
Every answer from a provider | default or preserve: the translation profile that applied |
x-vidai-adapted |
When translation changed, or couldn't carry, something you sent | Comma-separated names, in your SDK's own field names (seed,top_k; generationConfig.topK). The call succeeded (Any SDK to any provider) |
x-vidai-pseudonymised |
When a guardrail replaced personal data with stand-ins before the call, and put the originals back in the answer | 1. The text isn't exactly what the model produced, so think twice before caching it. Deliberately says nothing about what was found |
x-vidai-token-count |
On a token count the gateway made itself | tokenizer-match (same tokenizer family as the model) or estimated: how far to trust the number |
On the gateway's own errors¶
| Header | Value |
|---|---|
x-vidai-error-code |
The stable code: the same in every format. Match on it |
x-vidai-stage |
Where the call stopped: auth, rate_limit, routing, request_validation, request_translation, guardrail, upstream, telemetry, internal |
x-vidai-error-detail |
Why, in words, at most 512 characters. The body's message may be shorter |
x-vidai-source |
The format the error body is written in: openai, azure, anthropic, gemini or bedrock |
x-vidaiserver-version |
The gateway build that answered |
A provider's own error passes through with the provider's status and message, in your format, and with
x-vidai-model.
Not sent¶
- Cost. A call's cost is in Request logs and Money › Cost, never in the answer.
- Rate-limit headers (
retry-after,x-ratelimit-*) on the gateway's own 429. A provider's own pass through unchanged and describe the provider's limits, not your key's.
Read them from your SDK¶
raw = client.chat.completions.with_raw_response.create(model="gpt-4o-mini", messages=messages)
vidai = {k: v for k, v in raw.headers.items() if k.lower().startswith("x-vidai-")}
reply = raw.parse()
const { data: reply, response } = await client.chat.completions
.create({ model: "gpt-4o-mini", messages })
.withResponse();
const vidai = [...response.headers].filter(([k]) => k.startsWith("x-vidai-"));
curl -sS -D - -o /dev/null "$VIDAI_GATEWAY/v1/chat/completions" \
-H "Authorization: Bearer $VIDAI_KEY" -H "Content-Type: application/json" \
-d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hi"}]}'
Where a tool gives you no access to headers, everything they say is on the call in Request logs.