Gateway error codes
This page lists the errors that Fabric AI Gateway raises itself, as opposed to errors that it relays from a provider, MCP server, or API. For each error, it gives the HTTP status, what the body looks like on each kind of route, the cause, and what to do. To learn how to read and retry errors in your client, see Handle errors and retries.
How to tell a gateway error from an upstream error
When an upstream answers with an error status, the gateway relays the status, headers, and body unchanged. Everything on this page is different: the gateway wrote it.
Use these signals to tell them apart:
- The body. Gateway errors use the bodies listed on this page. An upstream error has the upstream’s own body, for example OpenAI’s or Anthropic’s error object with the provider’s message.
- The trace. Every response carries an
X-Request-Idheader. Find the request in Traces to see whether the upstream was called. For details, see Inspect traces.
A gateway 404 and an upstream 404 can look alike, and so can a gateway 502 and an upstream 502. When in doubt, check the trace.
Error formats by route type
The format of a gateway error depends on the route’s protocol and on which step raised it:
On LLM routes, errors about the request, the model, the provider, and paused services use the provider’s own envelope, so OpenAI and Anthropic SDKs can parse them. Some errors are still plain text or a small JSON object on every route type, for example the 401 from Key Auth and the 429 from the rate limit plugin. Each entry below says which format you get.
On an LLM route, the gateway sends errors that reveal configuration, such as an unknown endpoint, only after authentication succeeds. A caller without a valid key gets the authentication error first.
Jump to the group of errors that matches what you got:
Request doesn’t match a route
421 misdirected request
- Route types: all. Plain text
misdirected request. - Cause: The hostname in the request doesn’t belong to your organization’s data plane.
- What to do: Use the host from the URL that Copy LLM base URL or Copy DP URL gives you on the route. If your organization runs its own data plane, check that DNS and the load balancer send the hostname that an admin set in Admin > Data plane.
404 page not found
- Route types: all. Plain text
404 page not found. - Cause: No route in the request’s namespace matches its path and host. An eligible Default model router route also serves other namespaces that have no route of their own at the path. The gateway picks the namespace from the
fg-api-keyheader, not from the URL, so a route in another namespace gives404, and so does a request with no key when the route isn’t in the Default namespace. Paths are matched exactly: a missing base path, a typo, or a different letter case doesn’t match. - What to do: Compare the request path with the route’s base path and endpoints on LLMs > Routes, and check that your gateway key belongs to the route’s namespace. For an LLM route, the URL is the route’s base URL followed by the endpoint, for example
BASE_URL/v1/chat/completions.
404 unknown LLM endpoint
- Route types: LLM, in the provider envelope with type
invalid_request_errorand the messageunknown LLM endpoint. - Cause: The route exists, but no provider on it offers the endpoint you called. For example, you called
/v1/chat/completionson a route whose only provider speaks the Anthropic Messages API. The gateway never translates between API formats. - What to do: Call an endpoint that the route exposes, or add a provider that offers it. To see which endpoints each kind of provider offers, see Supported endpoints.
405 Method Not Allowed
- Route types: all. Plain text
Method Not Allowed, with anAllowheader that lists the accepted methods. - Cause: A route has this path, but not for this HTTP method.
- What to do: Use a method from the
Allowheader. Browser preflight (OPTIONS) requests also get this error, because the gateway doesn’t handle CORS.
400 invalid service override
-
Route types: LLM, in the provider envelope with type
invalid_request_error. -
Cause: One of the following, with its message:
-
What to do: Set the header to the name of a service on the route, or ask an admin to add a routing plugin, such as the LLM Router, that chooses between the services. For details, see Request and response headers.
Authentication and access
401 Unauthorized
- Route types: all. Plain text
Unauthorized. - Cause: The request has no gateway key, or the key isn’t valid for this route. A missing key and a wrong key get the same answer. A key that the gateway doesn’t know at all is refused before the route is matched, and a request with no key is served from the Default namespace.
- What to do: Send the gateway key in the
fg-api-keyheader. Check that the key hasn’t been revoked and that it belongs to the namespace and route you’re calling. For details, see Authenticate and send a request.
401 conflicting credentials
- Route types: all, on a route whose Key Auth reads the gateway key from a list of headers, such as
Authorization: Bearerandx-api-key. Plain textconflicting credentials. - Cause: The request carries more than one of those headers with different values, so the gateway can’t tell which one is the gateway key.
- What to do: Send the gateway key in one header only, or the same key in each.
401 missing or invalid token
- Route types: all routes with JWT Auth. JSON
{"error":"missing or malformed credentials"}or{"error":"invalid or expired token"}, with aWWW-Authenticate: Bearer resource_metadata="…"header. - Cause: The request has no bearer token, or the token is expired, has the wrong audience, or wasn’t issued by a configured identity provider.
- What to do: Get a new token from your identity provider. MCP clients follow the
resource_metadatalink to sign in. For details, see Authenticate requests with JWT Auth.
401 unauthorized on a gated route
- Route types: all. JSON
{"error":"unauthorized"}. - Cause: The service’s access mode is Gated, and the request didn’t identify a caller.
- What to do: Authenticate the request. A gated service also needs a grant for the caller.
403 access_denied
- Route types: REST and LLM: JSON
{"error":"access_denied"}. MCPtools/call: JSON-RPC error-32004tool not authorized, with HTTP200. - Cause: The caller is identified but has no grant for this gated service or tool.
- What to do: Ask an admin to grant access. For details, see Manage connections and routes.
403 forbidden
- Route types: REST and LLM: JSON
{"error":"forbidden","reason":"…"}. The status is configurable. MCP: JSON-RPC error-32003, with HTTP200. - Cause: A plugin that blocks all traffic matched the request. The
reasonis the text your admin configured. - What to do: Contact your admin. The block is deliberate.
403 access denied for model
- Route types: LLM routes with the
llm-model-routerplugin. Provider envelope: OpenAI typeauthentication_error, Anthropic typepermission_error. - Cause: The model exists on the route, but access rules remove every provider that serves it for this caller.
- What to do: Ask an admin for access to the model, or choose a model you can use. For details, see Control model access.
403 x-gateway-service does not match the routing policy
- Route types: LLM, in the provider envelope with type
authentication_errorand the messagex-gateway-service does not match this route's routing policy. - Cause: On a route with several services, you named one service in the
x-gateway-serviceheader, but the route’s routing plugin sends the request to a different service that you have no access to. - What to do: Remove the header, name a service that you have access to, or ask an admin to grant access to the service that the route uses.
401 upstream_auth_required
- Route types: REST and LLM: JSON
{"error":"upstream_auth_required","message":…,"provider":…,"consumer":…,"service":…,"authorize_url":…}. MCP: JSON-RPC error-32001with the link in the message and indata.authorize_url, with HTTP200. - Cause: The upstream needs a credential of your own, such as your account at an MCP server, and you haven’t connected it yet. Your gateway key was accepted.
- What to do: Open the
authorize_urland connect your account, then retry. For details, see Connect your accounts.
Request content
400 model not allowed
- Route types: LLM, in the provider envelope with type
invalid_request_errorand the messageModel "<model>" is not allowed for service "<service>". - Cause: The connection’s model filter doesn’t include the model you asked for.
- What to do: Use a model that the connection allows, or ask an admin to change the connection’s Model filter.
400 could not determine a model
- Route types: LLM, in the provider envelope with type
invalid_request_errorand the messageCould not determine a model for service "<service>". - Cause: The connection allows only some models, and the gateway couldn’t read the
modelfrom the request: the body isn’t valid JSON, has nomodelfield, or is larger than 10 MiB. - What to do: Send a JSON body with a
modelfield, under 10 MiB.
400 failed to read LLM request body
- Route types: LLM, in the provider envelope with type
invalid_request_error. - Cause: The gateway couldn’t read the request body, for example because the client closed the upload early.
- What to do: Retry the request. If it keeps failing, check the client’s network path to the gateway.
404 model not found
- Route types: LLM routes with the
llm-model-routerplugin. Provider envelope: OpenAI typeinvalid_request_errorwith codemodel_not_found, Anthropic typenot_found_error. The message ismodel `<name>` not found. - Cause: The model name doesn’t match a provider and model on the route, or an alias. Names have the form
<provider>/<model>, for exampleopenai/gpt-4o-mini, or are an alias with no/. - What to do: List the models you can call with
GET /v1/modelson the route, and use one of the names it returns. For details, see Route requests by model name.
400 model not available on this endpoint
- Route types: LLM routes with the
llm-model-routerplugin. Provider envelope with typeinvalid_request_errorand the messagemodel `<name>` is not available on `<method> <path>`. - Cause: The model exists, but none of its providers offer the endpoint you called, for example an Anthropic model on
/v1/chat/completions. - What to do: Call the endpoint that the model’s provider supports, such as
/v1/messagesfor Anthropic models.
400 invalid request body for model routing
- Route types: LLM routes with the
llm-model-routerplugin. Provider envelope with typeinvalid_request_error. The message isrequest body must be a JSON objector`model` is required. - Cause: The body isn’t a JSON object, or has no
modelstring. - What to do: Send a JSON object with a non-empty
modelfield.
413 request body too large
- Route types: LLM routes with the
llm-model-routerplugin: provider envelope with the messagerequest body too large(Anthropic typerequest_too_large). MCP: JSON{"error":"mcp_body_too_large"}. - Cause: The body is larger than 10 MiB (
llm-model-routerroutes) or 8 MiB (MCP). - What to do: Send a smaller request. For all size limits, see Limits.
400 invalid MCP request
-
Route types: MCP.
-
Body and cause: One of the following:
-
What to do: Update the MCP client, or fix the request it sends.
404 MCP method not found
- Route types: MCP. JSON-RPC
-32601Method not found: <method>, with HTTP404. - Cause: The method isn’t one the gateway serves for the protocol revision the client uses.
- What to do: Check that the client and the MCP server speak the same protocol revision.
422 validation_failed
- Route types: REST and LLM: JSON
{"error":"validation_failed"}. The status is configurable. MCP: JSON-RPC-32006request validation failed, with HTTP200. - Cause: The request breaks a request-validation rule that your admin configured.
- What to do: Fix the request so that it matches the route’s validation rules.
408 Request Timeout
- Route types: REST: plain text
Request Timeout. LLM: provider envelope with typeinvalid_request_errorand the messagerequest body upload timed out. The gateway closes the connection afterward. - Cause: The client’s upload stalled for longer than the service’s write timeout.
- What to do: Check the client’s network. Don’t retry blindly: the delay is on the client side.
Limits and quotas
429 Too Many Requests
- Route types: all. Plain text
Too Many Requests. - Cause: A rate limit plugin on the route ran out of requests for this caller in the current window.
- What to do: Wait and retry. The
Retry-AfterandRateLimit-*headers are sent only when the plugin instance is set to show headers. Without them, back off exponentially. For details, see Rate limits.
429 Token budget exhausted
- Route types: LLM. JSON
{"error":{"type":"rate_limit_exceeded","message":"Token budget exhausted","retry_after":<seconds>}}, with aRetry-Afterheader. The same body is sent to OpenAI and Anthropic clients. - Cause: The caller used up the token budget that the LLM Rate Limit plugin sets for the current window.
- What to do: Wait for the number of seconds in
Retry-After, then retry.
429 LLM budget exhausted
- Route types: LLM. JSON
{"error":{"type":"llm_budget","message":"LLM budget exhausted"}}. There’s noRetry-Afterheader. - Cause: The organization’s or the namespace’s spending budget is set to Block requests, and its spending has reached the limit for the current period.
- What to do: Wait for the period to reset, or ask an admin to raise the budget. For details, see Control spend with budgets.
503 LLM budget unavailable
- Route types: LLM. JSON
{"error":{"type":"llm_budget","message":"budget accounting unavailable"}}. The message can also bebudget configuration invalid. - Cause: The budget is set to Block requests, and the gateway can’t read its spending counter or its configuration, so it fails closed. A budget that only tracks spending never rejects a request for this reason.
- What to do: Retry with backoff. If it persists, ask an admin to check the budget. For details, see Control spend with budgets.
503 Rate limit not applied
- Route types: all. Plain text
Rate limit not applied: request carries no identity to countorRate limit not applied: limiter unavailable. - Cause: The rate limit counts per caller or per credential, and the request didn’t identify one. The second message means the plugin’s configuration is invalid.
- What to do: Authenticate the request. The response has no
Retry-Afterheader, because retrying the same request doesn’t help. If you’re an admin, either require authentication on the route or count the rate limit across all callers.
402 billing block
-
Route types: REST: JSON
{"error":"<reason text>","reason":"<reason>"}, with HTTP402. LLM: provider envelope with typeinvalid_request_errorand the message<reason text>: <reason>, with HTTP402. MCP: JSON-RPC-32002with the reason text as the message anddata.reason, with HTTP200. -
Cause: Your organization’s usage is blocked for billing reasons. The
reasonsays which:Any other reason has the text
billing quota exceeded. Branch onreason, not on the text. -
What to do: An admin can review usage in Admin > Usage & Billing.
Service and upstream availability
503 service paused
- Route types: REST: JSON
{"error":"service paused","service":"<service>"}. LLM: provider envelope with typeserver_errorand the messageservice paused: <service>. MCP: JSON-RPC-32005service pausedwithdata.service, with HTTP200. - Cause: The service’s owner paused it.
- What to do: Retry after the service is resumed, or ask its owner.
503 killswitch_active
- Route types: all. Plain text
killswitch_active. - Cause: An admin turned on the Killswitch plugin for this traffic.
- What to do: Contact your admin. Traffic resumes when they turn it off.
503 Service Unavailable
- Route types: REST and MCP: plain text
Service Unavailable. LLM: provider envelope, OpenAI typeserver_erroror Anthropic typeapi_error, with the messageno upstream is available. On a route with thellm-model-routerplugin, the message isno candidate for model `<name>` is available. - Cause: The gateway had no upstream to try: every upstream is unhealthy or skipped by its circuit breaker, the route has no service, or the gateway couldn’t load the upstream credential.
- What to do: Retry with backoff. If it persists, check the connection’s upstreams and credentials, and look at the request in Traces.
503 service unavailable (data plane starting)
- Route types: all. Plain text
service unavailable(lowercase). - Cause: The request carries a gateway key, but the data plane hasn’t received its configuration yet, for example right after it starts.
- What to do: Retry after a few seconds. If you run your own data plane and this persists, see Troubleshooting.
502 Bad Gateway
- Route types: REST and MCP: plain text
Bad Gateway. LLM: provider envelope, OpenAI typeserver_erroror Anthropic typeapi_error, with the messageupstream request failed(on a route with thellm-model-routerplugin,no candidate for model `<name>` is available). - Cause: The gateway tried the upstream, and the network connection failed before an answer arrived. On REST and MCP routes, this also covers the service’s overall timeout. On an LLM route, this also covers a streamed answer whose first event was malformed or cut short, when no fallback was left.
- What to do: Retry if the request is safe to repeat. If it persists, check that the connection’s target URL is reachable from the data plane.
504 Gateway Timeout
- Route types: REST: plain text
Gateway Timeout. LLM: provider envelope, OpenAI typeserver_erroror Anthropic typetimeout_error, with the messageupstream timed out(on a route with thellm-model-routerplugin,no candidate for model `<name>` is available). - Cause: The upstream didn’t send its response headers within the service’s read timeout, or an LLM upstream timed out. On REST routes, the service’s overall timeout gives
502 Bad Gatewayinstead. The request did reach the upstream, so the gateway doesn’t retry it. - What to do: Retry if the request is safe to repeat. For long-running requests, ask an admin to raise the service’s timeout. For defaults, see Limits.
503 upstream_auth_unavailable
- Route types: REST: JSON
{"error":"upstream_auth_unavailable",…}, withRetry-After: 5. MCP: JSON-RPC-32002withdata.typeupstream_auth_unavailable, with HTTP200andRetry-After: 5. Clients on MCP protocol revision 2026-07-28 can get-32012instead. - Cause: The gateway couldn’t get the upstream credential right now, for example because the credential store is still loading or a token refresh failed.
- What to do: Retry after 5 seconds. If it persists, reconnect your account.
503 credential_not_provisioned
- Route types: REST and MCP: JSON
{"error":"credential_not_provisioned","consumer":…,"service":…}. - Cause: The credential exists, but this data plane has no value for it.
- What to do: If you run your own data plane, check that its vault can read the credential. For details, see Manage credentials.
503 upstream_auth_exchange_failed
- Route types: all. JSON
{"error":"upstream_auth_exchange_failed",…}. - Cause: The gateway couldn’t sign the request to the upstream, for example with AWS credentials for Amazon Bedrock.
- What to do: Check the connection’s cloud credentials, such as the role or access key and region.
MCP tool call errors
MCP tool calls through the gateway can also return these JSON-RPC errors with HTTP 200:
On protocol revision 2026-07-28, a caller who opens more than 10 notification streams with subscriptions/listen gets HTTP 503 with JSON-RPC -32603, the message subscription stream unavailable, and Retry-After: 30. Close an old stream, then retry after 30 seconds.
Gateway faults
500 Internal Server Error
- Route types: all. Plain text
Internal Server Error. - Cause: An unexpected error inside the gateway.
- What to do: Retry once. If it repeats, contact support with the
X-Request-Idvalue.
500 plugin misconfigured
- Route types: depends on the plugin. Examples: JWT Auth sends
{"error":"jwt-auth: unknown provider"}. Upstream auth sends{"error":"upstream_auth_misconfigured","service":"<service>"}. The LLM Router sends the provider envelope with typeserver_errorand a message that starts withllm-router:. - Cause: A plugin’s configuration can’t work for this request, for example JWT Auth names an identity provider that doesn’t exist.
- What to do: An admin needs to fix the plugin instance. Retrying doesn’t help.
502 policy plugin failure
- Route types: all. Plain text
policy plugin failure. - Cause: A plugin that is set to fail closed broke while it handled the request, for example because it couldn’t reach a service it depends on. The upstream wasn’t called.
- What to do: Retry. If it persists, an admin can find the failing plugin in Traces.
502 access check unavailable
- Route types: LLM, in the provider envelope with type
server_errorand the messageinternal server error. - Cause: On a route with several services, the gateway had to check your access to the service that the routing plugin chose, and the access check couldn’t give an answer. The upstream wasn’t called.
- What to do: Retry. If it persists, contact support with the
X-Request-Idvalue.
502 Policy Error
- Route types: all. Plain text
Policy Error. - Cause: The gateway couldn’t work out which plugins apply to the request.
- What to do: Retry. If it persists, contact support with the
X-Request-Idvalue.
503 session pin unavailable
- Route types: LLM routes with the Adaptive Model Router. Provider envelope with the message
adaptive-model-router: session pin unavailable. - Cause: The router couldn’t read or store the model that it pinned for your session.
- What to do: Retry. If it persists, remove the session header to route without pinning.
502 response validation failed
- Route types: REST. JSON
{"error":"response_validation_failed"}(status configurable) or{"error":"response_validation_unavailable"}. None of the upstream’s headers or body reach the client. - Cause: The upstream’s response broke a response-validation rule, or the validator itself failed.
- What to do: Check the upstream’s response against the route’s validation rules.
Next steps
- Handle these errors in your client by following Handle errors and retries.
- Find fixes by symptom in Troubleshooting.
- Look up the headers that come with errors in Request and response headers.

