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

# Troubleshoot Fabric AI Gateway

> Find the cause of common errors when you send requests, configure routes, or run a data plane, and how to fix them.

This page lists common problems by symptom, grouped by what you were doing: sending requests, configuring the gateway, or running your own data plane. Each entry gives the likely causes and links to the page that covers the fix. For every error the gateway returns, see [Gateway error codes](/reference/error-codes).

Before you start, find the request in **Traces**. Every response carries an `X-Request-Id` header, and the trace shows whether the request reached the upstream. If it did, the error came from the provider or API, not from the gateway. For details, see [Inspect traces](/use/monitor/traces).

## Find the right troubleshooting topic

Start here for any problem, then go to the topic that covers your situation in depth.

| If you're                                                               | Go to                                                |
| ----------------------------------------------------------------------- | ---------------------------------------------------- |
| Getting a 401 or 403, or you don't know which step refused your request | [Troubleshoot access](/use/troubleshoot-access)      |
| Deciding which errors to retry, or reading rate-limit responses         | [Handle errors and retries](/use/errors-and-retries) |
| Looking for what happened to one request                                | [See your requests](/use/see-your-requests)          |
| Running your own data plane                                             | [Troubleshoot the data plane](/run/troubleshooting)  |
| Looking for a specific error code                                       | [Gateway error codes](/reference/error-codes)        |

## Sending requests

### 401 Unauthorized

The gateway didn't accept your credential. Check the following:

* You send the gateway key in the `fg-api-key` header, not in `Authorization` or the provider's own header, such as `x-api-key`.
* The key is current. A revoked or rotated key gets `401`.
* The key belongs to the namespace that owns the route. The key selects the namespace, so a key from another namespace doesn't reach that namespace's routes.
* If the route uses JWT Auth, the token isn't expired and comes from a configured identity provider.

If the body is `upstream_auth_required`, your gateway key was accepted. The upstream needs an account of your own: open the `authorize_url` and connect it. For details, see [Connect your accounts](/use/mcp/connect-your-accounts).

If the `401` body is the provider's own error, for example an Anthropic `authentication_error`, the provider rejected the gateway's credential for it. An admin needs to check the connection's credentials. For details, see [Manage credentials](/configure/credentials).

For the steps to authenticate, see [Authenticate and send a request](/use/authenticate).

### 403 Forbidden

You're authenticated, but you aren't allowed to make this request:

* `access_denied`: the connection's access mode is **Gated** and you have no grant for it. Ask an admin for access.
* `forbidden`, with a `reason`: a plugin that blocks traffic matched your request.
* `access denied for model`: you can't use any provider for that model. See [Control model access](/configure/access-and-limits/model-access).

### 404 Not Found

Check which body you got:

* `404 page not found` (plain text): no route matches the path and host. Compare the URL with the route's base path and endpoints on **LLMs** > **Routes**. Paths are matched exactly, including letter case.
* `unknown LLM endpoint`: the route exists, but none of its providers offer that endpoint. For example, an Anthropic route doesn't serve `/v1/chat/completions`. See [Supported endpoints](/reference/supported-endpoints).
* The provider's own `404`: the request reached the provider, which didn't recognize the path or model.

### Model not found or not allowed

* `Model "<model>" is not allowed for service "<service>".`: the connection's **Model filter** excludes the model. Use another model, or ask an admin to allow it.
* ``model `<name>` not found``: on a route that routes by model name, the name doesn't match a provider and model or an alias. Call `GET /v1/models` on the route and use a name from the list. For details, see [Route requests by model name](/configure/routing/model-router).
* ``model `<name>` is not available on `<method> <path>` ``: the model's providers don't offer that endpoint. Call the endpoint that its provider uses, such as `/v1/messages` for Anthropic models.
* `Could not determine a model`: the body isn't JSON, has no `model` field, or is over 10 MiB.

### 429 Too Many Requests

* Plain text `Too Many Requests`: a rate limit on the route ran out for you. Wait and retry with backoff. If the response has a `Retry-After` header, wait that many seconds.
* `Token budget exhausted`: you used up your token budget for the current window. Wait for the seconds in `Retry-After`.
* The provider's own `429`: the provider is rate limiting the gateway's account. If the route has more than one provider, the LLM Router can fail over on `429`. See [Fail over across providers with the LLM Router](/configure/routing/failover).

For how to configure limits, see [Rate limits](/configure/access-and-limits/rate-limits).

### 502, 503, or 504

These usually mean the gateway couldn't get an answer from the upstream:

| Status | Common causes                                                                                                                  | What to do                                                                                                                               |
| ------ | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `502`  | The network connection to the upstream failed. `policy plugin failure` means a plugin on the route broke.                      | Retry if the request is safe to repeat. Check the connection's **Target URL**.                                                           |
| `503`  | No upstream was available, the connection is paused, a Killswitch is on, or the gateway couldn't load the upstream credential. | Read the body: `service paused`, `killswitch_active`, and `upstream_auth_unavailable` each name the cause. Otherwise retry with backoff. |
| `504`  | The upstream didn't answer within the connection's timeout.                                                                    | For long requests, ask an admin to raise the timeout.                                                                                    |

### Errors that my SDK can't parse

Some gateway errors are plain text or a small JSON object, even on LLM routes, for example the `401` from Key Auth. An OpenAI or Anthropic SDK reports these as an unknown error and doesn't show the message. Read the raw response body, or find the request in **Traces**. For which errors use which format, see [Gateway error codes](/reference/error-codes#error-formats-by-route-type).

## Configuring the gateway

### A new route or change doesn't take effect

Changes reach the data plane a few seconds after you save them. If a request still gets the old behavior, wait a moment and retry. If you run your own data plane, check its status in **Admin** > **Gateway health**.

### MCP tools are missing

When a client calls `tools/list`, the gateway builds the list from every MCP server on the route. A tool can be missing for these reasons:

* **The server needs your account.** The list shows a `connect_<service>` tool instead of that server's tools. Call it, or open the link it returns, to connect your account. The gateway then notifies clients that listen for changes that the tool list changed. For details, see [Connect your accounts](/use/mcp/connect-your-accounts).
* **The server didn't answer.** A server that fails or takes longer than 30 seconds is left out of the list, with no error. Check that the server is up and that its **Target URL** is right.
* **You don't have access.** Tools of a **Gated** connection that you have no grant for are removed.
* **Tool Search is on.** The list contains only `search_tool`, `get_tool`, and `execute_tool`. Use `search_tool` to find the others.
* **The name changed.** On a route with several MCP connections, each tool name starts with a prefix for its server, such as `<prefix>__<tool>`.
* **Your client cached the list.** Reconnect the client, or reload its tools.

For the setup steps, see [Connect an MCP server](/configure/connections/mcp-servers).

### Requests go to the wrong provider

* On an LLM route with several connections, a routing plugin such as the LLM Router chooses the connection. Check its targets and their order. See [Route LLM requests across models and providers](/configure/routing).
* Without a routing plugin, a request to an LLM route with several connections must name one in the `x-gateway-service` header, or it gets `400`. The header sends the request to that connection only, with no failover.
* A REST route with several connections and no routing plugin sends every request to the first connection.
* To see which model answered, check the `model` field in the response, or `x-fabric-model` on a route that routes by model name.

### Browser requests fail with 405 or 401

The gateway doesn't handle CORS. A browser's preflight `OPTIONS` request gets `405` or `401`, and responses carry no `Access-Control-*` headers. Call the gateway from a server, not directly from a browser.

## Running a data plane

These entries apply if your organization runs its own data plane. For install, migration, enrollment, telemetry, and embedder problems, see [Troubleshoot the data plane](/run/troubleshooting).

### 421 misdirected request

The hostname in the request isn't the one the data plane serves for your organization. Check that DNS and your load balancer send the host that an admin set in **Admin** > **Data plane**, and that clients use the URL from **Copy LLM base URL** or **Copy DP URL**. For details, see [Connect a data plane](/run/connect-a-data-plane).

### 503 right after startup, or 502 for an upstream on your network

See [Troubleshoot the data plane](/run/troubleshooting#traffic).

### 503 credential_not_provisioned

The credential exists, but this data plane can't read a value for it. Check that the data plane's vault is set up and holds the credential. See [Secrets and keys](/run/secrets-and-keys) and [Manage credentials](/configure/credentials).

### Health checks

Point your load balancer at `/healthz`. The Helm chart points all of its Kubernetes probes at `/healthz`. It answers on any hostname and needs no credential. For the other health endpoints, see [Monitor the data plane](/run/monitor#health-endpoints). For details, see [Gateway API reference](/reference/gateway-api#endpoints-the-gateway-answers-itself).

## Next steps

* Look up a specific error in [Gateway error codes](/reference/error-codes).
* Handle errors in your client by following [Handle errors and retries](/use/errors-and-retries).
* Find answers to common questions in the [FAQ](/help/faq).
* Fix data plane problems with [Troubleshoot the data plane](/run/troubleshooting).
* To check timeout values, see [Limits](/reference/limits#timeouts).