Agents & Editors
Troubleshooting
Errors coding agents, editors and chat apps can return through Multi-Router, with their causes and fixes.
Errors that Multi-Router returns to a tool arrive in the tool's own format, so the tool shows them as it would show a provider error, with Multi-Router's message. Errors from the provider itself, such as a provider rate limit, pass through unchanged. The tables below list Multi-Router's messages by area.
Setup and sign-in
These errors mean the tool's settings are incomplete or in the wrong place:
| Symptom or message | Cause | Fix |
|---|---|---|
| Claude Code shows its login screen | The settings did not reach the Claude Code process. | Put the settings in ~/.claude/settings.json, or start Claude Code from the shell where they are set. |
401 invalid or missing API token | The Multi-Router API key is missing, mistyped, disabled or expired. | Check the key in the tool's settings, and its status in API Keys. |
400 your MR API token was sent in authorization, or in x-api-key | On a Claude Proxy with the Developer credential source, the Multi-Router key is in the header that carries the provider login. The message names that header. | Move the key to X-MR-Api-Token. For Claude Desktop, switch the Claude Proxy to the Organization credential source instead. |
400 X-MR-Router is required on the Bedrock ingress | A Bedrock request has no X-MR-Router header. | Add X-MR-Router to ANTHROPIC_CUSTOM_HEADERS. |
400 X-MR-Router is required on the Google Vertex ingress | A Vertex request has no X-MR-Router header. | Add X-MR-Router to ANTHROPIC_CUSTOM_HEADERS. |
403 insufficient_scope | The API key lacks a scope the request needs. | Add inference, and models:read for Claude Desktop or model discovery. |
404 the requested model or router was not found from a tool on an Adaptive Router | The X-MR-Router value is wrong, or the API key is limited to other routers. | Copy the router id from the router's page, and check the key's router access. |
| Model errors on the Anthropic route that name no Claude Proxy | The request has no X-MR-Router header, so it is routed by its model name as an ordinary request instead of through the Claude Proxy. | Add X-MR-Router to ANTHROPIC_CUSTOM_HEADERS. |
Models
A Claude Proxy refuses a model it does not serve with 404 and one of these messages:
| Message | Cause |
|---|---|
model 'X' is not a known model | The name matches no model in the catalog. |
model 'slug' is disabled on this router | The model is switched off on the Claude Proxy. |
model 'slug' is not available on <route> in <region> | The route's provider does not offer the model in that region. |
model 'slug' is not in group <group> | The model is outside the Custom route's model group. |
model 'slug' is not available in group <group> | The model is in the group, but its provider or region is not offered for it. |
model 'slug' is served on <provider>, not available on the <format> endpoint | The tool uses a format that does not match the route, such as the Bedrock format on an Anthropic route. |
model 'slug' is <lifecycle> | The model is retired or otherwise out of service, and the message gives its status. |
An API key limited to specific routers receives a single 404 for any of these, so the key reveals nothing about other routers: the requested model or router was not found on the Anthropic route, and Claude Proxy not found on Bedrock and Vertex routes. When Claude Code's model picker lists models the proxy no longer serves, run /model; if the list stays the same, delete ~/.claude/cache/gateway-models.json and restart Claude Code.
Access and limits
These errors come from the organization's controls. On the Anthropic route, budget errors have the error type budget_exhausted. On the Bedrock and Vertex routes they carry the header x-mr-error-code: budget_exhausted.
| Status | Message | Cause |
|---|---|---|
| 403 | this Claude Proxy is disabled | The Claude Proxy was disabled. |
| 429 | budget <id> is exhausted for this period; it resets at <time> | A budget with a period reached its cap. The Retry-After header gives the seconds until it resets. |
| 429 | budget <id> is exhausted | A lifetime budget reached its cap. |
| 429 | per-token rate limit exceeded | The API key sent more requests than its rate limit allows. |
Claude Proxy configuration
These errors mean the Claude Proxy needs attention from an admin:
| Status | Message | Fix |
|---|---|---|
| 403 | this Claude Proxy has no routing configuration; save it with a route before it can serve | Choose a route on the Claude Proxy and save it. |
| 503 | this Claude Proxy's Organization key is unavailable | Enable the provider key, or choose another on the Claude Proxy. |
| 503 | this Claude Proxy has no provider key for its route | Add a provider key for the route's provider. |
| 503 | this Claude Proxy is on the Custom route without a model group; re-save it | Choose a model group and save the Claude Proxy. |
| 503 | this Claude Proxy's route `X` is not in the current catalog; re-save it | Choose a current route and save the Claude Proxy. |
| 502 | Amazon Bedrock request failed | Bedrock could not be reached. Retry, and check the Bedrock key. |
| 503 | this Claude Proxy could not authenticate to Amazon Bedrock | Check the Bedrock key's credentials and region. |
| 503 | this Claude Proxy's Bedrock key configuration is unavailable | Check the Bedrock key, or choose another on the Claude Proxy. |
| 503 | region `X` differs from the region its Bedrock API key was minted for | Use a Bedrock key created for the route's region, or choose that key's region on the route. |
| 502 | Google Vertex request failed | Vertex could not be reached. Retry, and check the Vertex key. |
| 503 | this Claude Proxy's Google OAuth token is not ready; retry shortly | Retry after a few seconds. |
Adaptive Router
Tools that send OpenAI Chat Completions to an Adaptive Router see these errors:
| Symptom or message | Cause | Fix |
|---|---|---|
| 400 with a list of the models the router serves | The model is not switched on in the router's model group, or is not in the group. | Use a model id from the list, or switch the model on in the router's model group. |
404 for /v1/responses | The tool sent the OpenAI Responses format, which an Adaptive Router does not serve. Goose does this for some OpenAI models. | Choose a model the tool sends with Chat Completions, or use a Codex Proxy for Codex CLI. |
| Requests do not appear under the router in Traffic | The tool did not send X-MR-Router, such as Goose's desktop app or Cline's Anthropic provider. | Use the tool's OpenAI-compatible connection with the header, as on its page. |
Codex Proxy
A Codex Proxy refuses requests whose model it does not serve with 400 and one of these messages:
| Message | Fix |
|---|---|
`X` is not an OpenAI model | Choose an OpenAI model in model. A Codex Proxy forwards to OpenAI only. |
`X` names a router, not a model | Send an OpenAI model id in model, and the router id in X-MR-Router. |
| A message that the model is unknown | Use an OpenAI model id from the Multi-Router catalog. |