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

> Work out which step refused your request — the gateway key, access control, or the upstream credential — and who can fix it.

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](/use/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.

| Step                   | What the gateway checks                                                                                                                                            | What you see                                                                                                                                                                                                                                   | Who fixes it                                                                                                                                                                                                                                                                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Namespace           | Your `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 `Unauthorized`                                                                                                                                                                                                                      | You, if you have a valid key. Otherwise your admin.                                                                                                                                                                                                                                                                                               |
| 2. Route               | The 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 key         | The route accepts your key.                                                                                                                                        | `401` with `Unauthorized`, or `invalid or expired token`                                                                                                                                                                                       | You, if you have a key. Otherwise your admin.                                                                                                                                                                                                                                                                                                     |
| 4. Access control      | Your 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. Limits              | Your key is within its rate limits and budgets.                                                                                                                    | `429` with `Too Many Requests`, or a JSON-RPC error for a used-up quota                                                                                                                                                                        | You, by waiting. Or your admin, by raising the limit.                                                                                                                                                                                                                                                                                             |
| 6. Upstream credential | The 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](/use/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

* [Troubleshoot Fabric AI Gateway](/help/troubleshooting), for problems by symptom
* [Handle errors and retries](/use/errors-and-retries)
* [See your requests](/use/see-your-requests)
* [Understand credentials and keys](/concepts/credentials-and-keys)
* To send an authenticated request, see [Authenticate and send a request](/use/authenticate).