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.
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-Idresponse 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
- Troubleshoot Fabric AI Gateway, for problems by symptom
- Handle errors and retries
- See your requests
- Understand credentials and keys
- To send an authenticated request, see Authenticate and send a request.

