Skip to navigation

Troubleshoot access

A request through Fabric AI Gateway passes several checks, and each one can refuse it for a different reason. You can fix the first three yourself if you have a valid key. For the others, you usually need an admin. This topic is a diagnostic checklist. It lists the checks in a typical order so you can tell which one refused your request, and shows what to send your admin. The order isn’t a guarantee: a key that the gateway doesn’t know is refused before route matching, and some plugins run by scope and priority, so don’t assume that an earlier check passed because of the error you received. For every error shape, see Handle errors and retries.

Work through the checks

Find the check that matches what you got back. Start with step 1 if you’re not sure.

StepWhat the gateway checksWhat you seeWho fixes it
1. NamespaceYour fg-api-key header picks the namespace. With no key, the request goes to the Default namespace. With a key the gateway doesn’t know, the request stops here.401 with UnauthorizedYou, if you have a valid key. Otherwise your admin.
2. RouteThe path matches a route in that namespace.404 with 404 page not found. On an LLM route, a path that the route doesn’t serve returns 404 with unknown LLM endpoint, but only after your key is accepted, so you see it after step 3.You. Check the base URL and path, and check that your key belongs to the route’s namespace.
3. Gateway keyThe route accepts your key.401 with Unauthorized, or invalid or expired tokenYou, if you have a key. Otherwise your admin.
4. Access controlYour key is allowed to use this connection.403, such as access_denied. On an LLM route with a model router, access denied for model `<name>` . On an MCP route, JSON-RPC error -32004.Your admin.
5. LimitsYour key is within its rate limits and budgets.429 with Too Many Requests, or a JSON-RPC error for a used-up quotaYou, by waiting. Or your admin, by raising the limit.
6. Upstream credentialThe provider accepts the credential that the gateway sends.The provider’s own 401 or 403, in the provider’s own format. For a per-user connection you haven’t connected yet, the gateway itself returns 401 with upstream_auth_required and an authorize_url (on MCP, JSON-RPC error -32001).Depends on whose credential it is. For a gateway-managed credential, your admin or the operator who manages the connection. For a Passthrough route, a Lightyear route that uses your own provider credentials, or a per-user connection, you: replace your own provider key, or open the authorize_url from the error to connect your account.

Check the namespace first

The URL doesn’t pick the namespace. Your gateway key does, and a key works only in the namespace that issued it. If you get 404 for a route that exists, the most likely cause is a key from a different namespace, or no key at all, which sends the request to the Default namespace. Only the fg-api-key header picks the namespace. A key sent in Authorization or x-api-key doesn’t, so the request goes to the Default namespace.

Tell step 3 from step 6

Steps 1, 3, and 6 can all return 401, so read the body. The gateway never rewrites an upstream’s error, so a 401 that comes from the provider carries the provider’s own message and format, such as an OpenAI or Anthropic error body. A 401 from step 1 or 3 is plain-text Unauthorized or conflicting credentials, or, on a route with JWT Auth, JSON such as {"error":"invalid or expired token"}. JSON alone doesn’t mean the upstream sent it, because a provider’s 401 uses the provider’s own error format. JWT Auth can also reject an expired token at step 3, so a key the gateway knows doesn’t rule it out. When the body is ambiguous, send your admin the X-Request-Id response header. They can read fabric.error.origin (client, gateway, or upstream) in the access log.

If you can’t tell, send your admin the X-Request-Id response header. They can look the request up in the logs. A trace may not exist, because the collector drops requests that matched no route unless they ended in a 5xx, and it samples the rest. For details, see See your requests.

Ask for access

When the gateway refuses a request at step 4, you can’t approve it yourself, and the gateway doesn’t send a request for you. Tell your admin the following:

  • The route’s base URL and path.
  • The connection or model you tried to use.
  • The status and message you got.
  • The X-Request-Id response header.

If you’re an AI agent, report that access control refused the request and ask the user to contact their admin. Don’t retry the request.

Next steps