"Model Not Found" and Other OpenAI API Errors: A Complete Troubleshooting Guide

TL;DR

OpenAI’s 404 “model does not exist or you do not have access to it” almost never means the model is gone — it means one of five things, in this order: your account tier can’t see it (40% of cases), you typed the model ID wrong (25%), you called the wrong endpoint for that model (15%), the model was deprecated (15%), or you’re hitting Azure with an OpenAI client (5%). With GPT-5.5 and GPT-5.5 Pro now sitting above the GPT-5.4 family, tier locks are hitting more developers than at any point in the past year. This guide walks every cause with a verified fix, then gives you a 30-second decision tree so you stop guessing. Skip to the decision tree if your production is down.

Why OpenAI returns 404 instead of 403

The reason every “permission denied” error looks like a “doesn’t exist” error is intentional. OpenAI returns HTTP 404 — not 403 — when your API key is valid but doesn’t have access to the requested model. This is documented behavior, confirmed across hundreds of community threads. The official rationale is that revealing the existence of higher-tier models to lower-tier accounts would leak the product roadmap.

The practical consequence: the error message is misleading and you cannot trust it literally. A 404 on gpt-5.5-pro does not mean GPT-5.5 Pro doesn’t exist. It means your key can’t see it. Until you internalize this, you will waste hours debugging typos in model names that are spelled correctly.

The full error body looks like this:

{
  "error": {
    "message": "The model `gpt-5.5-pro` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": null
  }
}

Note the or you do not have access to it clause. That clause is doing more work than the rest of the message combined.

Cause 1: Your tier can’t access this model (most common)

OpenAI gates model access by usage tier. Tiers 1 through 5 are determined by your cumulative paid spend plus days since your first successful payment — not a rolling 30-day window. The newest, most expensive models are restricted to higher tiers.

Quick check — list what your key can actually call:

curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models | jq '.data[].id'

This endpoint returns the ground truth. The model catalog page on platform.openai.com shows what exists; the /v1/models call shows what your key can use. Trust the second one.

Fix path:

1. If you’re a new account on Tier 1: pay down at least $50 in usage and wait 7 days. You’ll auto-promote to Tier 2. Most “missing model” cases at Tier 1 are tier locks, not missing models.
2. If you need access immediately: use an aggregator like ofox.ai that pools access across higher-tier accounts. A single key sees every model regardless of your spend history. This is the fastest unblock for production deadlines. See our LLM API gateway guide for the architectural picture.
3. If you’re an enterprise account: file a tier review with OpenAI support. Tier promotions for verified business accounts often complete in 24-48 hours.

Tier-by-model access (as of mid-2026 — verify against your dashboard, as OpenAI adjusts gating frequently):

Cause 2: You typed the model name wrong

Model IDs are case-sensitive, hyphenated, and unforgiving. Some of the most common typos I’ve seen in production tickets:

Three rules that fix 90% of typos:

1. Always lowercase.
2. Hyphens between every component, never underscores or dots.
3. If you got the ID from a blog post older than 6 months, verify it’s still alive before deploying.

A reliable trick: copy model IDs from your /v1/models output, never from documentation prose. That output is canonical.

Cause 3: Wrong endpoint for that model

Starting in 2026, OpenAI runs two parallel APIs and not every model is available on both:

• Chat Completions (/v1/chat/completions) — legacy, still supported, broader model coverage
• Responses API (/v1/responses) — newer, agentic features, GPT-5.4 Pro and reasoning models land here first

Per OpenAI’s migration guide, GPT-5.4 with reasoning: none does not support tool calling on Chat Completions. GPT-5.4 Pro is Responses-only — call it on /v1/chat/completions and you get a 404.

How to tell which endpoint a model needs:

# This will work for Chat Completions models
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{"role": "user", "content": "ping"}]
  }'

# Responses-only models need this endpoint
curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4-pro",
    "input": "ping"
  }'

If the first request 404s but the second succeeds, you found your bug. Switch your SDK calls accordingly — for the official Python library, that means client.responses.create() instead of client.chat.completions.create().

Cause 4: The model was deprecated

OpenAI deprecates models with surprisingly little warning. Recent retirements that broke production for a lot of people:

• GPT-4o in ChatGPT: retired February 13, 2026. In the API, only the chatgpt-4o-latest alias was removed (February 17, 2026); the dated snapshot gpt-4o-2024-05-13 remains callable until October 23, 2026
• GPT-4 base (gpt-4-0613): still callable via the API but on the same October 23, 2026 shutdown date — migrate now, not later
• gpt-4-0125-preview, gpt-4-1106-preview, gpt-4-turbo: final API shutdown October 23, 2026
• gpt-4-vision-preview: shut down December 6, 2024
• gpt-4-32k variants: shut down June 6, 2025
• codex-mini-latest: removed from API February 12, 2026 — migrate to gpt-5-codex-mini
• gpt-4.5-preview: shut down July 14, 2025; superseded by the GPT-5 line
• o4-mini: removed from ChatGPT February 13, 2026; the API snapshot o4-mini-2025-04-16 is scheduled for shutdown October 23, 2026

The pattern: the entire GPT-4 family is on a single October 23, 2026 cliff. GPT-4.1 still appears in the catalog today, but if your code references any gpt-4* ID, treat it as a future outage and migrate.

The replacement table (battle-tested mappings):

To stay ahead of deprecations, subscribe to OpenAI’s deprecations page and add a CI check that calls /v1/models and fails the build if any production model ID disappears. Five lines of code, saves an outage. For broader resilience patterns, see our AI API error handling guide.

Cause 5: You’re hitting Azure with an OpenAI client

This one trips up teams migrating between vanilla OpenAI and Azure OpenAI. The two services have different URL structures and different model naming conventions:

If you use a stock OpenAI Python client with OPENAI_API_KEY set to an Azure key, every call will 404 because the base URL is wrong. Use AzureOpenAI from the same SDK package, or switch to a gateway that normalizes both backends.

The other Azure gotcha: deployment names are not model names. If you deployed a model and named the deployment my-prod-gpt, your API calls must use my-prod-gpt, not gpt-5.4. This is on you, not OpenAI.

Cause 6: Region or country block (403 disguised as 404)

OpenAI blocks API access from several countries. Requests from blocked regions sometimes surface as 403, sometimes as 404 depending on the exact request path. If you’re hitting the API from a VPS in a sanctioned region or through certain proxy networks, you’ll see “model not found” errors that disappear the moment you switch regions.

Check whether geography is your problem:

curl -v https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" 2>&1 | grep -E "HTTP|error"

A 403 with unsupported_country_region_territory confirms the region block. The fix is one of:

1. Route through a region-allowed origin (your own proxy, not a public one)
2. Use a gateway that exposes a regional-neutral endpoint — most aggregators handle this by hosting in supported regions and acting as a forward proxy. ofox.ai, OpenRouter, and similar services all do this transparently.

The 30-second fix tree

When production is on fire, run this in order:

1. Did this code work yesterday?
   YES → likely deprecation. Check OpenAI deprecations page.
   NO → continue to 2.

2. Run: curl -H "Authorization: Bearer $KEY" https://api.openai.com/v1/models | jq '.data[].id' | grep <your-model>
   FOUND → your model exists for your key. Bug is in endpoint or request body. Go to 4.
   NOT FOUND → continue to 3.

3. Is the model name correct, lowercase, hyphenated, current?
   YES → tier lock. Pay down usage, request promotion, or use a gateway.
   NO → fix the name.

4. Try the other endpoint:
   /v1/chat/completions → /v1/responses (or vice versa)
   Works → SDK/endpoint mismatch. Update your client call.
   Still 404 → continue to 5.

5. Are you hitting Azure?
   YES → use AzureOpenAI client, pass deployment name not model ID, include api-version.
   NO → continue to 6.

6. Check region. Run curl -v and look for unsupported_country_region_territory.
   FOUND → use a gateway or change egress region.

If step 6 doesn’t resolve it, you have a genuinely new problem and it’s time to open a ticket with OpenAI support.

Other OpenAI errors worth knowing alongside 404

While 404 dominates community questions, a few neighbors are worth a paragraph each:

401 Unauthorized — invalid or revoked key. The most common cause isn’t a wrong key but trailing whitespace when copying from a dashboard. Run printf "%s" "$OPENAI_API_KEY" | wc -c and verify the length matches what you expect.

403 Forbidden — IP allowlist mismatch or org policy block. Check your project settings on platform.openai.com under “Limits.”

429 Too Many Requests — covered in depth in our error handling guide. Always honor the Retry-After header.

500/502/503 — provider-side. Retry with exponential backoff. If it persists more than 10 minutes on a single model, route traffic to a fallback model via a gateway. See our API aggregation guide for the multi-provider failover pattern.

400 Bad Request with context_length_exceeded — your prompt plus expected completion exceeds the model’s context window. Not a 404 problem but often confused with one when error messages aren’t read carefully.

A note on switching to a unified gateway

If you’re hitting “model not found” because of tier locks or region blocks, the architectural fix — not just the tactical one — is putting a gateway between your app and OpenAI. A gateway like ofox.ai gives you an OpenAI-compatible endpoint that covers GPT-5.5, GPT-5.4, GPT-5.4 Pro, GPT-5.4 Mini, GPT-5.4 Nano, GPT-5.3 Chat, and GPT-5.3 Codex, plus every Claude, Gemini, DeepSeek, Qwen, and Llama model on the market.

Migrating is two lines:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key=os.environ["OFOX_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello"}],
)

For deeper migration patterns including drop-in compatibility considerations, our OpenAI SDK migration guide walks the full playbook.

What to do this afternoon

If you’ve been chasing “model not found” errors:

1. Run the /v1/models curl command above. Print the result somewhere visible. That list is your real model catalog.
2. Grep your codebase for any GPT-4 family model IDs. Anything containing gpt-4, gpt-3.5, o1, o4-mini, or vision-preview is a future outage waiting to happen.
3. Add a CI gate that calls /v1/models on every deploy and fails the build if your production model IDs are missing. This single check would have prevented most of the recent deprecation-related outages I’ve seen.
4. If you have production deadlines and your tier is too low, evaluate a gateway. The tier-lock class of error disappears entirely once you’re not calling OpenAI directly.

The OpenAI API is reliable. The model identifier system is not. Treat it accordingly.