Skip to content

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.