Troubleshoot Fabric AI Gateway
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.
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.
Find the right troubleshooting topic
Start here for any problem, then go to the topic that covers your situation in depth.
Sending requests
401 Unauthorized
The gateway didn’t accept your credential. Check the following:
- You send the gateway key in the
fg-api-keyheader, not inAuthorizationor the provider’s own header, such asx-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.
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.
For the steps to authenticate, see Authenticate and send a request.
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 areason: 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.
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.- 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. CallGET /v1/modelson the route and use a name from the list. For details, see Route requests by model name.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/messagesfor Anthropic models.Could not determine a model: the body isn’t JSON, has nomodelfield, 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 aRetry-Afterheader, wait that many seconds. Token budget exhausted: you used up your token budget for the current window. Wait for the seconds inRetry-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 on429. See Fail over across providers with the LLM Router.
For how to configure limits, see Rate limits.
502, 503, or 504
These usually mean the gateway couldn’t get an answer from the upstream:
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.
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. - 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, andexecute_tool. Usesearch_toolto 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.
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.
- Without a routing plugin, a request to an LLM route with several connections must name one in the
x-gateway-serviceheader, or it gets400. 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
modelfield in the response, orx-fabric-modelon 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.
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.
503 right after startup, or 502 for an upstream on your network
See Troubleshoot the data plane.
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 and Manage 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. For details, see Gateway API reference.
Next steps
- Look up a specific error in Gateway error codes.
- Handle errors in your client by following Handle errors and retries.
- Find answers to common questions in the FAQ.
- Fix data plane problems with Troubleshoot the data plane.
- To check timeout values, see Limits.

