# Headers

> Every request and response header the gateway reads or sets, in one table.

URL: https://boelabs.com/en/docs/ai-gateway/headers
Language: English

## Request headers

| Header | Where | Effect |
|---|---|---|
| `Authorization: Bearer <key>` or `x-api-key: <key>` | All `/v1/*`, all `/admin/*` | Auth. Master key on `/admin/*`; master or virtual key on `/v1/*`. |
| `x-request-id` | Any request | Echoed back on the response if you send it; otherwise the gateway generates one. Always log this — see [Troubleshooting](https://boelabs.com/docs/ai-gateway/troubleshooting). |
| `x-unified-cache: true` (or `1`) | Chat-shaped and embeddings requests | Opt in to response caching for this request. Ignored entirely for master-key traffic. |
| `x-unified-cache-ttl: <seconds>` | Same as above | TTL for a newly stored cache entry. Default `300`, max `86400`. Ignored if `x-unified-cache` isn't also set. |
| `x-unified-routing-metadata: true` (or `1`/`yes`/`on`/`include`) | `/v1/chat/completions`, `/v1/messages`, `/v1/responses` | Adds an `unified_routing` object to the response body (see below). |

## Response headers

| Header | When | Meaning |
|---|---|---|
| `x-request-id` | Always | Same value as the request's (or newly generated). |
| `x-ratelimit-limit-requests` / `-remaining-requests` / `-reset-requests` | Virtual-key requests with an RPM limit | Requests-per-minute budget for this key. |
| `x-ratelimit-limit-tokens` / `-remaining-tokens` / `-reset-tokens` | Virtual-key requests with a TPM limit | Tokens-per-minute budget for this key. |
| `x-ratelimit-limit-budget-cents` / `-remaining-budget-cents` / `-reset-budget` | Virtual-key requests with a spend budget | Remaining budget in cents, and seconds until the budget period resets. |

Rate-limit headers are per **virtual key**, not per model or deployment — they reflect the key's own
RPM/TPM/budget configuration (see [Virtual keys](https://boelabs.com/docs/ai-gateway/virtual-keys)). Master-key requests never carry
them (the master key has no limits). A cache hit is not signaled by any response header — it's only
visible in the operation log's `cacheHit` field via `GET /admin/logs`.

## `unified_routing` (response body, not a header)

Requested via the `x-unified-routing-metadata` header, added to the JSON body:

```json
{
  "unified_routing": {
    "served_model": "gpt-5.6",
    "reasoning_effort": "low",
    "routing_strategy": "latency-based",
    "unsupported_parameter_strategy": "drop",
    "fallback_used": false,
    "attempt_count": 1,
    "attempts": [
      { "index": 0, "ok": true, "latency_ms": 842 }
    ]
  }
}
```

`reasoning_effort` is the effort the served model ran at after [snapping](https://boelabs.com/docs/ai-gateway/reasoning), or `null`
when it does not reason. The block is returned by `/v1/chat/completions`, `/v1/responses` and
`/v1/messages`.

`attempts` includes every deployment the router tried for this request (including ones that failed
before the winning attempt), each with its latency and, on failure, `error_class` and `http_status`.
An attempt rejected as candidate-incompatible also carries `health_impact: "neutral"`.
See [Routing](https://boelabs.com/docs/ai-gateway/routing) for what `routing_strategy` and `fallback_used` mean, and
[Parameter policy](https://boelabs.com/docs/ai-gateway/parameter-policy) for `unsupported_parameter_strategy`.

## Next steps

- [Routing](https://boelabs.com/docs/ai-gateway/routing) and [Parameter policy](https://boelabs.com/docs/ai-gateway/parameter-policy) — what drives `unified_routing`.
- [Caching](https://boelabs.com/docs/ai-gateway/caching) — full semantics of the cache headers.
- [Virtual keys](https://boelabs.com/docs/ai-gateway/virtual-keys) — how RPM/TPM/budget limits are configured.