Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Find the symptom you see, confirm the cause, and apply the fix. Each section covers one area of model router in Microsoft Foundry: requests and responses, Auto (model router without a deployment), Claude models, quota, deployments and regions, per-request controls, and governance.
- Check the response's
modelfield first. It names the model that served the request, for examplegpt-5.6-luna-2026-07-09. - For routing details, send the
Foundry-Features: ModelRouterControls=V1Previewheader, and readmodel_selection_detailsin the response (preview). See Get per-request routing details. - For trends across requests, open the Monitor tab on your model router deployment. It shows latency, fallbacks, and requests by model.
- Invalid per-request controls fail with HTTP 400 before any model is called, and the error message names the problem.
Important
Features or capabilities marked (preview) in this article are in public preview and are subject to the Supplemental Terms of Use for Microsoft Azure Previews. Previews are provided without a service-level agreement, and Microsoft doesn't recommend them for production workloads. Certain features might not be supported or might have constrained capabilities.
Requests and responses
| Symptom | Cause | Resolution |
|---|---|---|
| A Messages API request returns HTTP 401. | The request sends the api-key header. The Messages API doesn't accept it. |
Send the key in the x-api-key header, or use a Microsoft Entra ID token in the Authorization header. See Authenticate. |
| Requests that use Microsoft Entra ID fail authentication or authorization. | The caller doesn't have the Foundry User role, or the token has the wrong scope. | Assign the Foundry User role (previously named Azure AI User) on the resource or project, and request tokens for the https://ai.azure.com/.default scope. See Role-based access control for Microsoft Foundry. |
| A Messages API request to a project endpoint fails. | The Messages API is available only on the resource endpoint. | Send Messages requests to https://<resource>.services.ai.azure.com/anthropic/v1/messages. See Choose an endpoint. |
A Messages API request without max_tokens fails. |
The Messages API requires max_tokens. |
Set max_tokens in every Messages request. See Use the Messages API. |
A parameter such as temperature has no effect. |
By default, model router drops optional parameters that the selected model doesn't support, such as temperature, top_p, or stop on reasoning models. |
To make every parameter mandatory, set routing_config.require_parameters to true (preview). Only models that support all the parameters you send are then eligible. See How model router handles parameters. |
| Reasoning effort has no effect, or the response doesn't report it. | Model router passes reasoning effort only to a selected model that supports it, and drops it otherwise. model_selection_details doesn't include the effort, and Claude models don't report it. |
Send effort in the native field: reasoning_effort (Chat Completions), reasoning.effort (Responses), or output_config.effort (Messages). routing_config has no reasoning-effort field. To require support, set routing_config.require_parameters to true. See How parameters and reasoning effort are handled. |
| A long request fails because it exceeds the context length. | The effective context window is the smallest context window among the models in your pool. | Route to a model subset of large-context models, or limit long requests to large-context models with routing_config.models (preview). Or shorten the prompt: summarize it, truncate it, or retrieve only the relevant sections. See Route to a subset of models. |
| A request with audio input doesn't work. | Model router doesn't support audio input. Image input is supported, but the routing decision uses only the text. | Send audio to a direct deployment of a model that accepts audio. See Limitations. |
| Model router selects a model you didn't expect. | Model router ranks models for each prompt, within your routing mode and your model pool or model subset. | Check the mode in model_selection_details.model_router_details.mode, and review your routing mode and model subset. To pin one request to a model, set routing_config.models to that model (preview). See How a request is routed. |
The model in the response differs from the first attempt in routing_trace. |
The first model failed with a retryable error, so model router failed over to the next-best eligible model. | No action is needed. To find models that fail often, check Fallback by source model on the Monitor tab. See Inspect routing attempts and failover. |
| A request fails without failing over. | The error isn't retryable, or no other eligible model is left. A model subset with one model has nothing to fail over to. | Check result.error in routing_trace for the cause. Include at least two models in your model subset. See Failover. |
| Latency is higher than expected. | End-to-end latency includes router overhead and the selected model's processing time, which varies by model. | On the Monitor tab, compare Router overhead with Model processing in Request latency, and use the By model view to find slow models. Then consider a model subset without them. See Use the Monitor tab. |
Auto
Auto (model router without a deployment) is in preview. For setup, see Send your first request with Auto.
| Symptom | Cause | Resolution |
|---|---|---|
A request with model set to auto returns HTTP 404 or a "deployment not found" error. |
The request uses the wrong host or path, or your resource is in a region where model router isn't available. There's no /auto path. |
Send the request to the /openai/v1/responses, /openai/v1/chat/completions, or /anthropic/v1/messages path on https://<resource>.services.ai.azure.com, with "model": "auto" in the request body. For Responses and Chat Completions, the project endpoint and the https://<resource>.openai.azure.com host also work. Check that your resource's region is listed in Supported regions. |
Requests with model set to auto use a deployment's settings instead of Auto. |
Your resource has a deployment named auto, and requests with that name go to the deployment. Likewise, model-router reaches Auto only when no deployment has that name. |
To use that deployment, keep calling it by name. To reach Auto, delete the deployment named auto, or use a resource that doesn't have one. See Choose Auto or your own deployment. |
Requests fail with Insufficient quota available for instant inference. |
All of your subscription's Global Standard model router quota is assigned to deployments. | Reduce or delete unused model router deployments to free quota, or request more quota. See Quota for Auto. |
| Auto doesn't use the Balanced routing mode or the full model pool. | An admin set Auto's routing mode or model subset for your resource in properties.instant.routing. |
Check the resource's Auto settings, or ask your admin. See Configure Auto for your resource. |
| Auto requests fail in a resource where they used to work. | An admin turned off Auto for the resource. Either properties.instant.modelAllowList leaves out model router, or it's an empty array, which turns off all instant access. |
Ask your admin to add model router back to the allow list, or use a model router deployment. See Configure Auto for your resource. |
| Content filtering for Auto differs from your deployment's. | Auto uses the resource's instant-access content filter setting, properties.instant.raiPolicyName, not a deployment's content filter. |
Set raiPolicyName for Auto, or use a model router deployment with a custom content filter. See Configure Auto for your resource. |
| Auto's routing mode, model subset, or content filter returned to its default after an update. | An update to properties.instant left out routing or raiPolicyName, which resets it. |
Send routing and raiPolicyName together in each update. See Configure Auto for your resource. |
An update to modelAllowList fails with HTTP 400 and the message Model '<format>/<name>/<version>' does not support instant inference. |
The model doesn't support instant access in your resource's region. | List only models that support instant access in your region. See Turn off Auto. |
Claude models
| Symptom | Cause | Resolution |
|---|---|---|
| Model router never selects a Claude model. | One of these causes: the Claude model isn't deployed in the same Foundry resource; the Claude deployment uses a version that isn't in the pool, such as the Azure-hosted version 2 that the Foundry portal selects by default; the model router deployment is Data Zone Standard; your model subset doesn't include it; or the request's model names a Claude model instead of your model router deployment or auto. Auto and deployments both need a Claude deployment in the resource. |
Deploy the Claude model in the same resource as a Global Standard deployment of the version in the supported models table, use a Global Standard model router deployment or Auto, include the Claude model in your model subset, and set model to your model router deployment name or auto. To send one request to a Claude model through model router, set routing_config.models to that model (preview). See Add Claude models. |
A Messages API request returns HTTP 400 with The Messages API requires a model router deployment that includes Anthropic models. |
Only Claude models answer Messages requests, and the model router deployment, or Auto, has no Claude deployment available. | Deploy a Claude model in the same Foundry resource, as described in the previous row. If your deployment uses a model subset, include the Claude model in it. See Use the Messages API. |
A new Claude model, such as claude-opus-5-5, never serves requests. |
Every Claude model needs its own deployment in the same Foundry resource. A model subset also doesn't pick up new models automatically. | Deploy the Claude model, and add it to your model subset if you use one. See Claude models. |
| Claude Code or the Claude Agent SDK doesn't use model router. | The environment variables that point these tools at the Messages endpoint and at your model router deployment aren't set. Only Claude models in the deployment answer. | Set CLAUDE_CODE_USE_FOUNDRY=1 and ANTHROPIC_FOUNDRY_RESOURCE=<resource>, and set ANTHROPIC_DEFAULT_SONNET_MODEL, plus the Opus and Haiku variables, to your model router deployment name. Authenticate with the Azure CLI or ANTHROPIC_FOUNDRY_API_KEY. Use a deployment rather than Auto for coding agents, because they send many large requests and need higher rate limits. See Claude Agent SDK and Claude Code. |
Quota and rate limits
| Symptom | Cause | Resolution |
|---|---|---|
| Requests to your model router deployment return HTTP 429. | Your traffic exceeds the deployment's tokens-per-minute (TPM) or requests-per-minute (RPM) limit. | Retry with exponential backoff, and watch the x-ratelimit-remaining-tokens and x-ratelimit-remaining-requests response headers. Increase the deployment's capacity, or request more quota. See When you reach the limit. |
| Routed requests are throttled even though your deployment of the underlying model has a higher limit. | A model router deployment's TPM and RPM limits apply to every request it routes, whichever model answers. | Raise the model router deployment's capacity, or request more model router quota. See How model router quota works. |
| Auto requests are throttled at low traffic. | Outside West US 3, Auto's limit is 1% of your subscription's model router quota. At Tier 1 (1,000,000 TPM), that's 10,000 TPM and 10 RPM. The portal doesn't show this limit. | Request a quota increase, or deploy model router for dedicated capacity. See Quota for Auto. |
| The quota request form doesn't seem to list model router. | Model router quota is requested as a model deployment quota. | In the quota request form, select Model Deployment as the quota type and Azure OpenAI as the model type, choose Global Standard or Data Zone Standard, and select ModelRouter as the model. See Increase your quota. |
| Your own deployment of a model doesn't seem to serve routed requests. | Model router uses your deployment only when it has the exact model name and version, is in the same Foundry resource, and has an eligible deployment type: provisioned throughput (Global Provisioned, Data Zone Provisioned, or Regional Provisioned) for OpenAI models, or pay-as-you-go (Standard, Global Standard, or Data Zone Standard) for any pool model. A Data Zone Standard model router deployment uses only your Data Zone Provisioned and Data Zone Standard deployments. | Deploy the exact model name and version from the model pool table in the same resource, with an eligible deployment type. Responses don't show which capacity served a request. See Use your own deployments for routed requests. |
| Usage on your own deployment of a model rises after you adopt model router. | Model router serves the selected model from your own deployments first (preview): your provisioned throughput (PTU) deployment for OpenAI models, and then your pay-as-you-go deployment. Those requests use that deployment's PTUs, or its quota and rate limits. On a pay-as-you-go deployment, you pay its usage plus the routing fee. | No action is needed. If your deployment returns a retryable error, such as HTTP 429, model router moves to the next capacity for the same model: your pay-as-you-go deployment after a provisioned one, and then router-managed capacity. See Quota when your deployments serve requests. |
Deployment and regions
| Symptom | Cause | Resolution |
|---|---|---|
| You can't find the routing mode or model subset options. | These options are in the new Foundry portal. | In the Foundry portal, turn on the New Foundry toggle, find model-router in the model catalog, select Deploy, and then select Custom settings. Or set them with the REST API, the Azure CLI (az rest), or Bicep. See Choose a routing mode. |
| You can't deploy model router, or the deployment type you want isn't offered. | Your resource's region doesn't support model router, or doesn't offer that deployment type. Global Standard is available in 32 regions, and Data Zone Standard in 23 of them. | Check your region and deployment type in Supported regions. Create a Foundry resource in a supported region if you need to. |
| You can't find model router in Azure Government. | Model router isn't available in Azure Government. | For the features that Azure Government offers, see Microsoft Foundry in Azure Government. |
| A routing mode or model subset change doesn't take effect. | Changes to the routing mode or model subset take up to five minutes. | Wait five minutes, and then check model_selection_details.model_router_details.mode or Requests by model on the Monitor tab. See Choose a routing mode. |
| A new model in the pool never serves your requests. | Deployments that use the full pool get new models automatically, but model subsets don't. In each region, model router routes only across the pool models available in that region. | Add the model to your model subset, and check that it's available in your region. See How the model pool changes. |
| A model in your subset retired. | Retired models leave the pool. The supported models table lists upcoming retirements. | Replace the retired model with a model from Supported models. Keep at least two models in the subset. |
| Your model router version is retiring. | Versions 2025-05-19 and 2025-08-07 retire January 27, 2027, and version 2025-11-18 retires May 20, 2027. A retirement date applies to that model router version, not to model router. |
Move deployments on 2025-05-19 or 2025-08-07 to 2025-11-18 before January 27, 2027. See Versions and lifecycle. |
Per-request controls
Per-request controls and session affinity are in preview. They need the Foundry-Features: ModelRouterControls=V1Preview header.
| Symptom | Cause | Resolution |
|---|---|---|
routing_config is ignored. |
The request doesn't include the Foundry-Features: ModelRouterControls=V1Preview header. Without it, model router ignores routing_config and routes normally. |
Send the header with every request that includes routing_config. In the OpenAI Python library, use extra_headers or the client's default_headers. See Turn on per-request controls. |
HTTP 400 with the message The routing_config field must be an object. |
routing_config isn't a JSON object. |
Send routing_config as an object. In the OpenAI Python library, pass it in extra_body. See Errors. |
HTTP 400 with the message The routing mode must be one of: quality, balanced, cost. |
routing_config.mode isn't a supported value. |
Use balanced, quality, or cost. The value isn't case-sensitive. See Choose a routing mode for one request. |
HTTP 400 with a message about routing models, such as The routing models field must be a non-empty array of model names. |
routing_config.models is empty, isn't an array, or has an entry that isn't a non-empty string. |
Send at least one model name without a version, for example ["gpt-5.6-sol", "claude-sonnet-5"]. See Limit a request to specific models. |
HTTP 400 with the code invalid_require_parameters. |
routing_config.require_parameters isn't a boolean. |
Send true or false, not a string. See Require support for every parameter. |
HTTP 400 with a message about session_affinity or its strategy. |
routing_config.session_affinity isn't an object, or its strategy isn't supported. |
Send an object with strategy set to adaptive, sticky, or none. See How session affinity works. |
HTTP 400 with the code invalid_routing_parameters and a message that no model can satisfy the parameter requirements. |
require_parameters is true, and no eligible model supports every parameter you sent. No model was called. |
Remove the parameter that no eligible model supports, add models that support it to routing_config.models, or set require_parameters to false. See Require support for every parameter. |
HTTP 400 with the code invalid_routing_parameters and a message that routing_config.parameters isn't supported. |
routing_config includes parameters or constraints. |
Send model parameters, such as temperature or reasoning effort, in the API's own request fields. See Errors. |
HTTP 400 with the message None of the requested routing models are available in this deployment. |
routing_config.models can only narrow routing. None of the listed models is in your deployment's model subset, or in the models that Auto can route to in your region. |
List models that the deployment or Auto can route to. Check the names against Supported models and your model subset. |
HTTP 400 with the message Every requested routing model must belong to the deployment pool. |
require_parameters is true, and routing_config.models lists a model that the deployment or Auto can't route to. |
Remove that model from routing_config.models, or add it to the deployment's model subset. |
A model in routing_config.models never serves the request. |
Model router ignores listed models that the deployment or Auto can't route to. For Auto, Claude models also need a deployment in your resource. | Check the names against Supported models and your model subset. See Limit a request to specific models. |
model_selection_details is missing from the response. |
The request didn't send the preview header, or you're reading a streaming event that doesn't carry the metadata. During the preview, every part of the metadata is optional. | Send the header. When you stream, read the metadata from the response.completed event (Responses), the final chunk without choices (Chat Completions), or the message_delta event (Messages). In the OpenAI Python library, read it from response.model_extra. See Get per-request routing details. |
| A conversation switches models between turns. | Without the header, model router routes each request independently. With the header, the default adaptive strategy switches when the previous model's prompt cache is likely cold, or when its expected quality for the turn isn't close to the best-ranked model. Policy, capability, quota, availability, and failover also take precedence over affinity. |
Check session_affinity.decision and routing_trace in the response. To try the previous model first on every turn, use the sticky strategy with a session ID. A sticky association expires after 30 minutes without a successful request. See Keep a session on one model with a session ID. |
| A session ID seems to be ignored. | Model router ignores an invalid session ID instead of returning an error. A valid session ID has 1–256 characters and isn't only whitespace. | Send a valid, opaque session ID that contains no secrets or personal data. See How session affinity works. |
Governance
| Symptom | Cause | Resolution |
|---|---|---|
| Your Azure Policy denies a model, but model router still routes to it. | Azure Policy is evaluated when a deployment is created or updated. It doesn't filter which models a deployment or Auto routes to at request time. | Limit routing to approved models with a model subset on each deployment, and with properties.instant.routing.models for Auto. Audit the deployments that existed before the policy. See How model router honors Azure Policy. |
| A model router deployment is rejected with a policy violation. | The deployment includes a model that your policy doesn't allow. | Remove the noncompliant model from the model subset, and deploy again. See Troubleshoot Azure Policy for model router. |
| Data must stay in a data zone, such as the EU, but you use Auto. | Auto always processes data as Global Standard. | Deploy model router with the Data Zone Standard deployment type in a region that offers it. See Data, privacy, and security. |
Get help
If your problem isn't listed here, try these resources:
- Model router FAQ answers common questions about Auto, quota, pricing, and governance.
- Known issues - Microsoft Foundry lists current platform issues.
- Stay informed about service health regressions shows how to get Service Health alerts.
- Foundry Tools support and help options explains how to open a support request.
When you open a support request, include the time of the request in UTC, your region, the API and endpoint, your deployment name or auto, the HTTP status and error code, and model_selection_details from the response if you have it. Don't include API keys or personal data.