Skip to navigation

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-Id header. 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:

Route typeFormat
LLM, OpenAI-compatible endpoints{"error":{"message":"…","type":"…","code":null}}, with Content-Type: application/json
LLM, Anthropic Messages endpoints{"type":"error","error":{"type":"…","message":"…"}}, with Content-Type: application/json
MCPA JSON-RPC 2.0 error, {"jsonrpc":"2.0","id":…,"error":{"code":…,"message":"…","data":{…}}}, usually with HTTP 200
REST (HTTP)Plain text or a small JSON object, as listed for each error

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-key header, not from the URL, so a route in another namespace gives 404, 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_error and the message unknown LLM endpoint.
  • Cause: The route exists, but no provider on it offers the endpoint you called. For example, you called /v1/chat/completions on 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 an Allow header 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 Allow header. 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:

    MessageCause
    x-gateway-service header must name a configured LLM serviceThe x-gateway-service header is present but empty.
    unknown LLM service "<name>" in x-gateway-service headerThe header names a service that isn’t on the route.
    x-gateway-service header is required for multi-service LLM routesThe route has several services and no routing plugin, so the request must name one.
  • 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-key header. 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: Bearer and x-api-key. Plain text conflicting 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 a WWW-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_metadata link 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"}. MCP tools/call: JSON-RPC error -32004 tool not authorized, with HTTP 200.
  • 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 HTTP 200.
  • Cause: A plugin that blocks all traffic matched the request. The reason is 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-router plugin. Provider envelope: OpenAI type authentication_error, Anthropic type permission_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_error and the message x-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-service header, 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 -32001 with the link in the message and in data.authorize_url, with HTTP 200.
  • 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_url and 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_error and the message Model "<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_error and the message Could not determine a model for service "<service>".
  • Cause: The connection allows only some models, and the gateway couldn’t read the model from the request: the body isn’t valid JSON, has no model field, or is larger than 10 MiB.
  • What to do: Send a JSON body with a model field, 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-router plugin. Provider envelope: OpenAI type invalid_request_error with code model_not_found, Anthropic type not_found_error. The message is model `<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 example openai/gpt-4o-mini, or are an alias with no /.
  • What to do: List the models you can call with GET /v1/models on 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-router plugin. Provider envelope with type invalid_request_error and the message model `<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/messages for Anthropic models.

400 invalid request body for model routing

  • Route types: LLM routes with the llm-model-router plugin. Provider envelope with type invalid_request_error. The message is request body must be a JSON object or `model` is required.
  • Cause: The body isn’t a JSON object, or has no model string.
  • What to do: Send a JSON object with a non-empty model field.

413 request body too large

  • Route types: LLM routes with the llm-model-router plugin: provider envelope with the message request body too large (Anthropic type request_too_large). MCP: JSON {"error":"mcp_body_too_large"}.
  • Cause: The body is larger than 10 MiB (llm-model-router routes) 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:

    BodyCause
    JSON {"error":"invalid_mcp_jsonrpc"}Strict schema validation is on, and the body isn’t valid JSON-RPC.
    JSON-RPC -32020 Header mismatch: …An MCP header disagrees with the body.
    JSON-RPC -32022The protocol revision the client named isn’t supported. data lists the supported revisions.
    JSON-RPC -32602 Invalid params: …The request’s envelope is missing or incomplete.
  • What to do: Update the MCP client, or fix the request it sends.

404 MCP method not found

  • Route types: MCP. JSON-RPC -32601 Method not found: <method>, with HTTP 404.
  • 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 -32006 request validation failed, with HTTP 200.
  • 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 type invalid_request_error and the message request 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-After and RateLimit-* 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 a Retry-After header. 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 no Retry-After header.
  • 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 be budget 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 count or Rate 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-After header, 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 HTTP 402. LLM: provider envelope with type invalid_request_error and the message <reason text>: <reason>, with HTTP 402. MCP: JSON-RPC -32002 with the reason text as the message and data.reason, with HTTP 200.

  • Cause: Your organization’s usage is blocked for billing reasons. The reason says which:

    reasonReason text
    payment_method_requiredpayment card required
    trial_expiredtrial ended; add a payment card to continue
    canceledbilling cancelled; resume billing to continue
    past_duepayment failed; update your payment card to continue
    balance_exhaustedrequest allowance exhausted; buy more credit to continue
    trial_cap_reachedtrial request allowance exhausted
    overage_limitspend limit reached
    credits_exhaustedcredit balance exhausted; top up to continue

    Any other reason has the text billing quota exceeded. Branch on reason, 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 type server_error and the message service paused: <service>. MCP: JSON-RPC -32005 service paused with data.service, with HTTP 200.
  • 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 type server_error or Anthropic type api_error, with the message no upstream is available. On a route with the llm-model-router plugin, the message is no 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 type server_error or Anthropic type api_error, with the message upstream request failed (on a route with the llm-model-router plugin, 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 type server_error or Anthropic type timeout_error, with the message upstream timed out (on a route with the llm-model-router plugin, 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 Gateway instead. 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",…}, with Retry-After: 5. MCP: JSON-RPC -32002 with data.type upstream_auth_unavailable, with HTTP 200 and Retry-After: 5. Clients on MCP protocol revision 2026-07-28 can get -32012 instead.
  • 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:

CodeMessageCauseWhat to do
-32603Credential resolution failedThe gateway couldn’t look up your credential for the tool’s server.Retry. If it persists, reconnect your account.
-32603Tool call failed: …The MCP server couldn’t be reached, or it answered with an HTTP error.Retry. Check that the MCP server is up.
-32601Tool not foundThe tool name has a known server prefix, but no such tool.Call tools/list again and use a name it returns.
-32002tools/list could not build the tool catalogThe credential store was unreadable, or no server on the route answered, so the gateway couldn’t build the catalog. The error’s data.type is catalog_unavailable and data.retryable is true.Retry after a few seconds. If it persists, check the connection’s target URL, or reconnect your account.
-32042URL elicitation requiredYou need to connect an account, and the client supports URL elicitation. On MCP protocol revision 2026-07-28, the code is -32013.Follow the link that the client shows.

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-Id value.

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 type server_error and a message that starts with llm-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_error and the message internal 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-Id value.

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-Id value.

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