> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Request and response headers

> The request headers that Fabric AI Gateway reads, the response headers it adds, and the headers it changes on the way to the upstream.

Fabric AI Gateway reads some request headers to authenticate and route a request, and adds some headers to the response. This page lists those headers, and what the gateway changes in the request that the upstream receives. Every other header passes through unchanged in both directions.

Header names aren't case-sensitive.

## Request headers the gateway reads

| Header                      | Route types | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fg-api-key`                | All         | Carries the gateway key. Key Auth reads the key from this header, and the key also selects the namespace whose routes serve the request. A request with no `fg-api-key` is served by the Default namespace's routes. A key that the gateway doesn't know is refused with `401` before any route is matched. Until the data plane has received its first configuration, a request that carries a gateway key gets `503`, so retry it. A request without a key gets `404`. Two different key values in the headers that the route reads get `401` with `conflicting credentials`. The gateway never forwards this header to the upstream. For details, see [Authenticate and send a request](/use/authenticate). |
| `Authorization`             | All         | With JWT Auth, carries `Bearer <token>` from your identity provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `x-gateway-service`         | LLM         | Sends the request to the named connection on the route, with no failover to other connections. On a route with several connections and no routing plugin, the header is required. A missing, empty, or unknown name gets `400`. On a route with the `llm-model-router` plugin, the gateway ignores this header: it doesn't change which providers are tried and never produces the `400`.                                                                                                                                                                                                                                                                                                                      |
| `X-Amr-Session-ID`          | LLM         | Pins a conversation to one model when the route uses the Adaptive Model Router, so that each turn reuses the same model and keeps the provider's prompt cache. The router also recognizes `X-Claude-Code-Session-ID`, `Thread-ID`, `Session-ID`, `Session_Id`, `X-Session-ID`, and `X-Session-Affinity`, in that order. It uses the first one that has a value. If that value is over 256 characters, the request isn't pinned: the router doesn't fall back to the next header. For details, see [Route requests with the Adaptive Model Router](/configure/routing/adaptive-routing).                                                                                                                        |
| `anthropic-version`         | LLM         | Forwarded to the provider unchanged. On a route with the `llm-model-router` plugin, it also makes `GET /v1/models` answer in Anthropic's list format instead of OpenAI's.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `X-Request-Id`              | All         | If you send one of up to 256 characters, the gateway uses it as the request ID, forwards it to the upstream, and returns it. Otherwise the gateway generates one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `traceparent`, B3 headers   | All         | If you send trace context, the gateway continues your trace and passes it on to the upstream.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `Mcp-Session-Id`            | MCP         | Identifies the MCP session. The gateway sets it in its answer to `initialize`, and the client sends it on later requests.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `MCP-Protocol-Version`      | MCP         | Names the MCP protocol revision. It must agree with the request body, or the gateway answers `400`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `Accept: text/event-stream` | MCP         | On a `GET`, opens the long-lived notification stream for the caller.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

An admin can set a Key Auth instance to read the gateway key from a list of headers instead, such as `Authorization: Bearer` and `x-api-key`, the headers that the OpenAI and Anthropic SDKs send. On such a route, Key Auth reads only those headers. If more than one of them carries a key and the keys differ, the request gets `401` `conflicting credentials`.

Headers that providers read, such as `anthropic-beta` and `OpenAI-Organization`, reach the provider unchanged.

## Response headers the gateway adds

| Header                                                                               | When                                                                    | Value                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Request-Id`                                                                       | Every response, including errors                                        | The request ID: yours, or one the gateway generated. Quote it when you contact support, and use it to find the request in **Traces**.                                                                                                                                                    |
| `x-fabric-model`                                                                     | LLM routes with the `llm-model-router` plugin, when a provider answered | The provider and model that answered, for example `openai/gpt-4o-mini`.                                                                                                                                                                                                                  |
| `X-Amr-Model`, `X-Amr-Tier`, `X-Amr-Escalations`, `X-Amr-Cost-Usd`, `X-Amr-Strategy` | LLM routes where the Adaptive Model Router answered in cascade mode     | The model that answered, its tier, how many times the router escalated, the estimated cost in USD, and the strategy it used.                                                                                                                                                             |
| `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`                          | A rate limit plugin instance that is set to show headers                | The configured limit, the requests left, and the seconds until the window resets. The gateway also sends the same three as `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. When several limits apply, the headers describe the one with the fewest requests left. |
| `RateLimit`, `RateLimit-Policy`                                                      | Same as above                                                           | `RateLimit` is `limit=…, remaining=…, reset=…`. `RateLimit-Policy` is `<limit>;w=<window seconds>`.                                                                                                                                                                                      |
| `Retry-After`                                                                        | Some `429` and `503` errors                                             | Seconds to wait before you retry. It's sent with a `429` from the LLM Rate Limit plugin, with a `429` from a rate limit instance that shows headers, and with `503` `upstream_auth_unavailable` (`5`).                                                                                   |
| `WWW-Authenticate`                                                                   | `401` from JWT Auth                                                     | `Bearer resource_metadata="<url>"`. MCP clients follow the link to sign in.                                                                                                                                                                                                              |
| `Allow`                                                                              | `405`                                                                   | The methods that the route accepts for the path.                                                                                                                                                                                                                                         |

On LLM routes, the provider's response is never compressed, because the gateway reads it to count tokens. If a provider compresses it anyway, the gateway decompresses it and removes `Content-Encoding` and `Content-Length`.

## What the upstream receives

The gateway forwards the request with these changes:

* **Your gateway credential is removed.** The `fg-api-key` header is always removed. So is the header that the authentication plugin read the key or token from.
* **The upstream credential is added.** For a provider, the gateway adds the credential from the connection in the provider's own header, such as `Authorization: Bearer …` or `x-api-key`, or signs the request, for example with AWS Signature Version 4 for Amazon Bedrock. A client header with the same name is replaced.
* **Forwarding headers are set.** `X-Forwarded-For` gets your address appended. `X-Forwarded-Proto` and `X-Forwarded-Host` are set if you didn't send them. `Host` is the upstream's host.
* **Console cookies are removed.** Cookies whose names start with `fabric_`, which the Fabric console sets, are removed from the `Cookie` header. Other cookies pass through.
* **Hop-by-hop headers are removed.** `Connection`, `Keep-Alive`, `Proxy-Authenticate`, `Proxy-Authorization`, `TE`, `Trailer`, `Transfer-Encoding`, and `Upgrade` aren't forwarded. Because `Upgrade` is removed, WebSocket connections don't work through the gateway.
* **Compression is turned off where the gateway reads the response.** `Accept-Encoding` is removed on LLM and MCP routes, and on REST routes whose responses are transformed or validated.
* **Trace context is added.** The upstream receives W3C `traceparent` and B3 headers for the current trace.

## Next steps

* Send your first authenticated request by following [Authenticate and send a request](/use/authenticate).
* Look up what each error status means in [Gateway error codes](/reference/error-codes).
* Configure rate limit headers in [Rate limits](/configure/access-and-limits/rate-limits).