Because Microsoft Foundry exposes the standard Claude Messages API behind an Azure front door, errors come from two layers: the Azure side (authentication, roles, regions, quota) and the Claude API side (request validation, model behavior). Knowing which layer produced an error is half the diagnosis. The other half is captured in two response headers — request-id and apim-request-id — which Anthropic asks you to provide together in support requests so a call can be traced across both Anthropic and Azure systems. Log both on every request.
The common codes, decoded
| Code / signal | Likely cause on Foundry | Fix |
|---|---|---|
| 401 / auth failure | Missing or wrong API key, or key sent in the wrong header | Pass the deployment's key in the api-key or x-api-key header (the SDK does this for you); fetch the current key from the deployment's Details tab in the Foundry portal |
| 403 with Entra ID | Token valid but role missing | Grant the caller a role such as Cognitive Services User (Microsoft's docs) / Foundry User or Cognitive Services User (Anthropic's docs) on the resource |
| 400 Bad Request on a feature call | Feature not supported on your hosting version — e.g. structured outputs, web search, code execution, MCP connector, or Files API against a "Hosted on Azure" deployment | By design, not an outage. Use a "Hosted on Anthropic infrastructure" deployment for those features, or switch technique (e.g. tool-based JSON) |
| 400 "prompt is too long" | Input alone exceeds the model's context window | Trim or summarize input; note newer-tokenizer models (Opus 4.7+, Sonnet 5, Fable 5) use ~30% more tokens for the same text |
| 429 Too Many Requests | RPM or ITPM quota exhausted — shared at subscription level across deployments of the same model+version | Jittered exponential backoff; add prompt caching (cache reads don't count toward ITPM); request a quota increase |
| "Region not available" | Deployment attempted in an unsupported region | Create the Foundry resource in a supported region (Global Standard: East US2 or Sweden Central); Anthropic's Supported Regions Policy may also restrict by billing country |
HTTP 200 with stop_reason: "refusal" | Not an error — a safety refusal. Claude Fable 5 applies additional input/output classifiers | Handle in application logic; refused input tokens are not billed. Check stop_details.category on models that provide it |
Errors that are really configuration mismatches
The model parameter is a deployment name, not a model ID. On Foundry you call your deployment, whose name defaults to the bare model ID (like claude-opus-4-8) but may have been customized at creation — and it cannot be renamed afterward. A request naming a deployment that does not exist in your resource fails regardless of whether the underlying model ID is valid. When a request that "should work" fails, list the deployments in your resource and compare exactly.
Retired beta headers keep old code working until they don't. A documented example: the Sonnet 4.5 1M-context beta header (context-1m-2025-08-07) was retired on April 30, 2026 — since May 1, requests over 200K tokens with that header on Sonnet 4.5 return an error. If a long-running service starts erroring without a deploy, check the model lifecycle notes.
Model-specific parameter rules produce 400s. On newer models, several once-valid parameters are rejected: manual extended thinking, non-default temperature/top_p/top_k, and assistant prefill all return 400 on Sonnet 5 and recent Opus models, and thinking: {type: "disabled"} errors on Fable 5. Errors that appear only after a model upgrade are usually this.
A diagnosis routine
- Read the status code and error body first. Foundry responses follow the standard Claude API format; the error type and message usually name the offending field.
- Ask "which layer?" 401/403/429/region errors are Azure-side (identity, roles, quota, placement); validation 400s and refusals are Claude-API-side.
- Ask "which hosting version?" If a feature call 400s, check whether your deployment is Hosted on Azure — most advanced features require Hosted on Anthropic.
- Reproduce minimally, then escalate with both
request-idandapim-request-idif the behavior still looks wrong.
Where to go next
For the 429 branch in depth, see handling rate limits and throttling on Foundry. Auth setup lives in Entra ID authentication and Foundry API keys; feature availability in Foundry feature parity.