Azure OpenAI — every API error, fix, and status
The complete developer reference for Azure OpenAI Service — 15 deep fix guides covering the errors that come up in production, from DeploymentNotFound to PTU throttling to Structured Outputs. All code tested against Azure OpenAI, verified July 2026.
What is Azure OpenAI?
Azure OpenAI Service is Microsoft's enterprise-grade hosted version of OpenAI's models — GPT-4o, GPT-4.1, o-series reasoning models, DALL-E, Whisper, and the text-embedding-3 family — with Azure's networking, identity, and compliance guarantees layered on top. It uses the same SDKs as openai.com but with subtly different semantics that catch developers off guard on their first production deploy.
This hub is the Azure-specific companion to our OpenAI hub. Where the two overlap (chat completions, tool use, JSON mode), we call out the Azure-specific differences. Where they don't — PTU deployments, Entra ID auth, private endpoints, content filter policies — we cover Azure exclusively.
Browse by category
Every Azure OpenAI error we've documented, grouped into the seven categories that matter for troubleshooting.
Routing & Deployment
Deployment name vs model ID, region binding, endpoint URL correctness.
Authentication & Networking
Entra ID (formerly AAD), managed identity, private endpoints, RBAC.
Capacity & Quotas
PTU throttling, DALL-E quotas, spillover to Standard.
Content Safety & Filters
Content filter categories, jailbreak detection, custom policies.
Model Lifecycle
Preview retirement, embedding migration, api-version pinning.
APIs & Integration
Streaming SSE differences, JSON mode, Batch API requirements.
Reliability & Outages
Regional outages, 5xx handling, cross-region failover.
All 15 Azure OpenAI errors
The complete list — sorted by page number. Each fix guide includes real error messages, root causes ranked by frequency, three tested fixes with working Python code, a seven-item prevention checklist, and five FAQs.
-
#1
Deployment name vs model ID — DeploymentNotFoundHTTP 404Routing & Deployment
-
#2
PTU capacity exceeded — reserved throughput throttlingHTTP 429Capacity & Quotas
-
#3
Content filter triggered — content_filter finish_reasonHTTP 400Content Safety & Filters
-
#4
Entra ID authentication failedHTTP 401Authentication & Networking
-
#5
Private endpoint connection failedHTTP 403Authentication & Networking
-
#6
DALL-E image quota exceededHTTP 429Capacity & Quotas
-
#7
gpt-4 preview model deprecatedHTTP 404Model Lifecycle
-
#8
Streaming (SSE) differences from OpenAIHTTP 200APIs & Integration
-
#9
Batch API — 24hr window, deployment SKUHTTP 400APIs & Integration
-
#10
text-embedding-ada-002 deprecatedHTTP 404Model Lifecycle
-
#11
Service outage — 503 and regional failoverHTTP 503Reliability & Outages
-
#12
Cognitive Services region mismatchHTTP 404Routing & Deployment
-
#13
Model deployment truly missingHTTP 404Routing & Deployment
-
#14
api-version query parameter requiredHTTP 400Model Lifecycle
-
#15
JSON mode — response_format quirksHTTP 400APIs & Integration
Model catalog (Azure OpenAI, 2026)
The current GA models on Azure OpenAI. Version numbers and availability shift — always cross-reference with the Azure OpenAI model availability page for your specific region.
| Model | Version | Context window | Max output | Use case | Status |
|---|---|---|---|---|---|
gpt-4o | 2024-08-06 | 128K | 4,096 | Chat + vision + tools | GA |
gpt-4o-mini | 2024-07-18 | 128K | 16,384 | Fast + cheap chat | GA |
gpt-4.1 | 2025 | 1M | 16,384 | Long-context flagship | GA |
o1 | 2024-12-17 | 200K | 100K | Reasoning | GA |
o3-mini | 2025 | 200K | 100K | Fast reasoning | GA |
text-embedding-3-small | — | 8K | — | Cheap embeddings (1536-dim) | GA |
text-embedding-3-large | — | 8K | — | High-quality embeddings (3072-dim) | GA |
dall-e-3 | — | 4K prompt | — | Image generation | GA |
gpt-image-1 | 2025 | — | — | Newer image model | GA |
whisper | — | 25MB audio | — | Speech-to-text | GA |
Deployment SKU quick reference
Azure OpenAI capacity comes in five flavours. Choose based on throughput needs, cost sensitivity, and data-residency requirements.
| SKU | Best for | Throttling model | Notes |
|---|---|---|---|
Standard | Dev, low volume | Regional RPM/TPM | Simplest, region-bound |
GlobalStandard | Best-effort production | Global RPM/TPM | Cross-region capacity, higher ceilings |
DataZoneStandard | EU/US data residency | Zone RPM/TPM | Compliance + cross-region absorption |
ProvisionedManaged (PTU) | Steady enterprise traffic | Reserved throughput % | Predictable capacity, spillover option |
GlobalBatch | Async large jobs | Enqueued tokens | 50% off real-time pricing, 24hr SLA |
Details in the individual fix guides — PTU throttling, Batch API, region mismatch.
Key differences from openai.com
Copy-pasted OpenAI code usually works on Azure until it hits one of these differences:
- Model parameter means deployment name, not model ID. See deployment name vs model ID.
- api-version query parameter is required on every request. See api-version required.
- Content filter is stricter by default and has additional categories (jailbreak, protected material). See content filter policy.
- Streaming includes extra chunks for prompt filter results and content filter results. See streaming differences.
- Entra ID auth is the recommended production auth method, with specific role assignment requirements. See Entra ID auth.
- Batch API requires a specific SKU (GlobalBatch) — not just a parameter. See Batch API.
Get the weekly AI-error digest
New fixes, provider status recaps, and one deep tutorial — every Tuesday. 8,400+ engineers.