> 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.

# Follow a request through the gateway

> Follow a request through the data plane, from route matching and authentication through the plugin chain and the upstream call to logging and metering.

Every request that reaches Fabric AI Gateway goes through the same steps on the data plane, whatever its protocol. A request can stop at several of these steps, for example when authentication fails. Once it stops, no later step runs and the upstream isn't called. This topic walks through the steps in order and explains where plugins run, what happens when a plugin fails, and what the gateway records afterward. For how the data plane and control plane fit together, see [How Fabric works](/evaluate/architecture).

## 1. Receive the request

The data plane gives the request an ID and starts tracing it. If you send an `X-Request-Id` header of up to 256 characters, the gateway keeps it. Otherwise, it generates one. The same ID goes to the upstream and comes back to you on the response. If you send W3C `traceparent` or B3 trace headers, the gateway joins your trace.

## 2. Find your organization and namespace

The host name decides whose configuration serves the request. From here on, the gateway uses only your organization's routes, connections, plugins, and credentials. Another organization's configuration never affects your requests.

The gateway then reads the `fg-api-key` header to pick the namespace. With no key, the request goes to the Default namespace. With a known key, it goes to that key's namespace. With a key that the gateway doesn't know, the request stops with `401`. The URL never picks the namespace, and only `fg-api-key` does: a key in `Authorization` or `x-api-key` doesn't.

The gateway then cleans the path: it resolves `.` and `..` segments and collapses repeated slashes. Every later step, and the upstream, sees the cleaned path.

A few paths are answered by the gateway itself instead of a route, such as `/healthz`, the OAuth sign-in endpoints for MCP clients, and the pages where users connect their accounts.

## 3. Match a route

The gateway looks for the route that serves the request among that namespace's routes only (except that an eligible Default model router route also serves other namespaces that have no route of their own at the path), by path, host, method, and any header conditions on the route. When several routes fit, the most specific path wins. For example, `/users/me` beats `/users/:id`, which beats `/users/*`. A route pinned to a host beats one that isn't, and after that the route's priority decides.

If the path exists but not for this method, you get `405` with an `Allow` header. If nothing matches, you get `404`. In both cases no plugin runs.

If the route has a path rewrite or a route prefix, the gateway works out the path that the upstream receives. Plugins and logs still see the path that you sent.

## 4. Read the protocol

For MCP, LLM, and A2A routes, the gateway reads the request body in that protocol's format, so later steps can use the model name, the MCP method, or the tool being called. The gateway reads up to 8 MiB of an MCP request and up to 10 MiB of an LLM request. An MCP request over its limit gets `413`. A REST request's body is read only if a plugin needs it.

## 5. Authenticate

Authentication plugins, such as Key Auth and JWT Auth, work out who is calling. Only those at the narrowest scope that has any run: route first, then connection, then global. A route with its own Key Auth replaces a global JWT Auth.

Each one looks for its own credential. The first that recognizes a valid credential identifies you, and the rest are skipped. A configured authentication plugin denies a missing or wrong credential with `401`, and the request ends there. If no authentication plugin applies, the request continues as anonymous.

## 6. Run the request plugins

Next, the request plugins run, such as rate limits, budgets, transforms, and redaction. The gateway also checks access here: if the connection is gated and you have no grant for it, the request is denied with `401` if you're anonymous, or `403` otherwise. Plugins attached to you as a consumer, or to your consumer group, apply from this step, because the gateway now knows who you are.

Plugins run in the following order:

* **By scope.** Global plugins run first, then connection, route, consumer group, and consumer plugins.
* **By priority.** Within a scope, each plugin's priority decides. Ties go by instance name.

Most plugins run once per request, at the narrowest scope that has an instance. Some, such as rate limits, are stackable: every matching instance runs, and the first one that's out of room refuses the request.

The first plugin that denies the request ends it with that plugin's response. No later plugin runs, and the upstream isn't called.

### When a plugin fails

A plugin can also fail, for example when it crashes or can't reach a connection it depends on. Each plugin instance has a failure mode that decides what happens next:

| Failure mode    | What happens                                                                                  |
| --------------- | --------------------------------------------------------------------------------------------- |
| **Fail closed** | The request stops with `502` and the body `policy plugin failure`. The upstream isn't called. |
| **Fail open**   | The gateway skips the plugin, logs the failure, and the request continues.                    |

A plugin that denies a request on purpose, such as a rate limit returning `429`, isn't failing. It denies whatever its failure mode is. The built-in plugins that cover authentication, authorization, and redaction fail closed by default.

## 7. Answer MCP requests at the gateway

On MCP routes, the gateway answers some requests itself instead of forwarding them: `initialize`, `ping`, and `tools/list`, which it builds from every MCP server on the route. A `tools/call` goes to the server that owns the tool. For details, see [Connect an MCP client to an MCP route](/use/mcp/connect-a-client).

## 8. Call the upstream

The gateway picks where to send the request. Usually that's the route's connection. A routing plugin, such as the LLM Router, can choose instead, and it can list several connections to try in order. Within a connection, the load balancer picks an upstream. If the connection has a circuit breaker configured, an upstream is skipped after a run of failures (5 in a row unless set otherwise) for a cool-down (30 seconds unless set otherwise), and then one trial request decides whether it's back. Health checks, which also take failing upstreams out of rotation, work the same way: only when they're configured on the connection.

Before it forwards the request, the gateway removes your gateway credential and adds the upstream's credential, so you never see the upstream's secrets. If the upstream needs your own account and you haven't connected it, the request stops with a link to connect it. For details, see [Connect your accounts to MCP servers](/use/mcp/connect-your-accounts).

If a try fails, the gateway can do the following, depending on how your admin configured the route:

* **Retry** the same upstream after a short wait that doubles each time.
* **Fail over** to the next connection in the list.

A failure that might have reached the upstream fails over only if repeating the request is allowed. LLM routes allow it by default, and other routes don't. Once the response starts reaching you, the gateway doesn't retry or fail over. For details, see [Fail over across providers](/configure/routing/failover).

## 9. Return the response

The gateway relays the upstream's status, headers, and body. Streams, such as server-sent events, are passed on event by event as they arrive. Response plugins, such as a response transform, run on the way back. If every try failed and nothing was sent yet, the gateway sends its own error instead. For what those errors look like, see [Handle errors and retries](/use/errors-and-retries).

## 10. Log and meter

After the response, the gateway finishes the request's records:

* **Access log.** Every request that reaches your organization's configuration gets exactly one access-log record, with the status that you received.
* **Traces and metrics.** The request's trace closes, with the route, connection, consumer, and, for LLM traffic, the provider and model.
* **Analytics, audit, and usage.** Plugins that record the request run now, for example to count tokens. A request that a plugin denied is recorded too.
* **Metering.** If the upstream answered, the request counts toward your organization's usage, as an API, MCP, LLM, or A2A request.

If the upstream call failed, error-handling plugins run instead of the normal completion plugins.

## Next steps

* To see where the data plane and control plane run, see [Choose a deployment model](/evaluate/deployment-models).
* To add plugins to a route, see [Control traffic with plugins](/configure/plugins).
* To follow one request in detail, see [Inspect traces](/use/monitor/traces).