Errors and headers
Every status and code the gateway returns, and every header it reads or sets.
Errors
Errors use OpenAI's envelope, so an SDK parses them with the code path it already has. A different shape would turn a clean 402 into an unhandled exception.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request_error | The body did not parse, or a field is out of range. OpenAI’s own code, so an SDK handles it with the path it already has. |
| 401 | invalid_api_key | The key is missing, malformed, revoked or disabled. |
| 402 | insufficient_quota | Not enough credit to cover the request. Top up and retry. |
| 402 | budget_exceeded | This key has reached its monthly cap. Raise it, or use another key. |
| 402 | plan_limit_exceeded | Your plan's allowance is used up, or you have as many of something as it permits. The message says which. |
| 403 | model_unavailable_in_region | The model is not available from the requesting region. |
| 404 | model_not_found | No such model id. Check /v1/models for the current catalogue. |
| 404 | request_not_found | No request with that id, when scoring one. |
| 400 | security_check_failed | A security check found something high severity, in block mode: prompt injection, a card number, an IBAN or an API key. The message names the kinds. Nothing was sent to a provider and nothing was charged. |
| 413 | request_too_large | The request body is larger than the gateway accepts. |
| 429 | rate_limit_exceeded | Too many requests on this key: too many at once, or too many requests or tokens in the last minute. retry-after says how long to wait. |
| 502 | provider_unavailable | No usable provider for that model, and no fallback succeeded. |
| 502 | upstream_error | The provider answered with an error we could not translate into anything more useful. |
Two of these are 402 and mean different things. A budget is a cap you set and can raise; a plan limit is answered by upgrading. The message says which.
Request headers
| Header | Meaning | |
|---|---|---|
| Authorization | required | Bearer vk_live_… Your gateway key. |
| x-vatan-prop-<name> | optional | An attribution tag. Up to 16 per request; values over 256 characters are truncated. |
| x-vatan-cache | optional | Seconds to allow a cached response for this exact request. Omit for no caching. |
| x-vatan-session-id | optional | Groups this request into a conversation. |
| x-vatan-session-name | optional | A label for that conversation. The first request to name one wins. |
| x-vatan-user-id | optional | Your own identifier for the person this request is for. Opaque to us. |
| x-vatan-prompt | optional | A stored prompt this request came from, as name or name@version. |
| x-vatan-security | optional | off, flag or block for this request, overriding the organisation's default. An unrecognised value falls back to that default rather than to off. |
Response headers
| Header | Meaning |
|---|---|
| x-vatan-request-id | This request's id. Post it to /v1/feedback to score the answer. |
| x-vatan-model | The model that actually served it, which differs from the one you asked for when a fallback was used. |
| x-vatan-cache | HIT or MISS. Only present when you sent x-vatan-cache. |
| retry-after | Seconds to wait, on a 429. |