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

# Gateway error codes

> Every error that Fabric AI Gateway returns itself, with its HTTP status, body, cause, and what to do.

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](/use/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](/use/monitor/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 type                        | Format                                                                                                                |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 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`                          |
| MCP                               | A 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:

#### [Route not found](#request-doesnt-match-a-route)

`404`, `405`, `421`

#### [Authentication and access](#authentication-and-access)

`401`, `403`

#### [Request content](#request-content)

`400`, `404`, `413`, `422`

#### [Limits and quotas](#limits-and-quotas)

`402`, `429`, `503`

#### [Service availability](#service-and-upstream-availability)

`502`, `503`, `504`

#### [Gateway faults](#gateway-faults)

`500`, `502`, `503`

## 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](/reference/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:

  | Message                                                             | Cause                                                                               |
  | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
  | `x-gateway-service header must name a configured LLM service`       | The `x-gateway-service` header is present but empty.                                |
  | `unknown LLM service "<name>" in x-gateway-service header`          | The header names a service that isn't on the route.                                 |
  | `x-gateway-service header is required for multi-service LLM routes` | The 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](/reference/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](/use/authenticate).

### 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](/configure/authentication/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](/configure/connections#set-the-access-mode).

### 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](/configure/access-and-limits/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](/use/mcp/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](/configure/routing/model-router).

### 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](/reference/limits).

### 400 invalid MCP request

* **Route types:** MCP.

* **Body and cause:** One of the following:

  | Body                                   | Cause                                                                                         |
  | -------------------------------------- | --------------------------------------------------------------------------------------------- |
  | 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 `-32022`                      | The 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](/configure/access-and-limits/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](/configure/access-and-limits/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](/configure/access-and-limits/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:

  | `reason`                  | Reason text                                                |
  | ------------------------- | ---------------------------------------------------------- |
  | `payment_method_required` | `payment card required`                                    |
  | `trial_expired`           | `trial ended; add a payment card to continue`              |
  | `canceled`                | `billing cancelled; resume billing to continue`            |
  | `past_due`                | `payment failed; update your payment card to continue`     |
  | `balance_exhausted`       | `request allowance exhausted; buy more credit to continue` |
  | `trial_cap_reached`       | `trial request allowance exhausted`                        |
  | `overage_limit`           | `spend limit reached`                                      |
  | `credits_exhausted`       | `credit 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](/help/troubleshooting#running-a-data-plane).

### 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](/reference/limits#timeouts).

### 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](/configure/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`:

| Code     | Message                                       | Cause                                                                                                                                                                                                | What to do                                                                                               |
| -------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `-32603` | `Credential resolution failed`                | The gateway couldn't look up your credential for the tool's server.                                                                                                                                  | Retry. If it persists, reconnect your account.                                                           |
| `-32603` | `Tool call failed: …`                         | The MCP server couldn't be reached, or it answered with an HTTP error.                                                                                                                               | Retry. Check that the MCP server is up.                                                                  |
| `-32601` | Tool not found                                | The tool name has a known server prefix, but no such tool.                                                                                                                                           | Call `tools/list` again and use a name it returns.                                                       |
| `-32002` | `tools/list` could not build the tool catalog | The 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. |
| `-32042` | URL elicitation required                      | You 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

* Handle these errors in your client by following [Handle errors and retries](/use/errors-and-retries).
* Find fixes by symptom in [Troubleshooting](/help/troubleshooting).
* Look up the headers that come with errors in [Request and response headers](/reference/headers).