Fix: "The model `X` does not exist or you do not have access to it" — OpenAI model_not_found

TL;DR — model_not_found (HTTP 404) means the model ID is not visible to the key you sent. Four real causes, in the order to check them: (1) the model needs access your org does not have yet, (2) you are on the wrong org/project for that key, (3) the model ID is subtly wrong — a date suffix, a preview name, a deprecated alias, (4) you are calling the wrong endpoint for that model family. Fastest diagnosis: list the models your key can see and compare, instead of guessing at spelling.

The error

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

The message deliberately merges two very different situations — "no such model" and "not yours" — which is why guessing at spelling wastes so much time.

Diagnose in one call

Before changing anything, ask the API what your key can see:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | grep -o '"id": "[^"]*"' | sort

If the model you want is missing from that list, it is an access/org problem, not a typo. If it is present but your call still 404s, it is an endpoint problem (see cause 4).

The four causes

1. Your org does not have access yet. New or gated models roll out by tier, and some require verification before they appear. Another developer's working snippet proves the model exists — not that your org can call it. Check the models list; if it's absent, access is the issue and no code change fixes it.

2. Wrong org or project. Keys are scoped. A key created under a project without access to a model 404s even when a sibling project in the same account works fine. If your account has multiple orgs/projects, confirm which one issued the failing key. Where an org header is in play, an explicit OpenAI-Organization value that doesn't match the key's scope produces the same 404.

3. The model ID is subtly wrong. The common shapes:

• A dated snapshot that has been retired (...-2024-xx-xx) while the alias still works — or the reverse.
• A preview/experimental name that has since been renamed at GA.
• A deprecated alias that now resolves to nothing.
• Copying a model name from a different provider entirely (see below).

4. Right model, wrong endpoint. Model families are not interchangeable across endpoints — a completions-only or embeddings model called on chat completions, or a reasoning-family model called on an endpoint that does not serve it, returns the same 404. Match the model to the endpoint its family is documented for.

The cross-provider trap

If you point an OpenAI-compatible client at a different provider's base URL, the model names change with it. Asking a Gemini or DeepSeek compatibility endpoint for gpt-4o returns a not-found error, because that model does not exist there — a very common failure right after switching a base URL. The related Gemini case is covered in the Google AI Studio base-URL guide, and the Cursor variant in overriding the OpenAI base URL in Cursor.

Fixes, by cause

| Cause | Fix | |---|---| | No org access | Request/await access; use a model your key can see meanwhile | | Wrong org/project | Use a key from the org that has access; check any org header | | Bad model ID | Copy the exact ID from the /v1/models output, not from a blog post | | Wrong endpoint | Call the endpoint that serves that model family | | Wrong provider | Use that provider's own model names after a base-URL change |

Prevention

• Never hardcode a single model ID in a long-lived agent. Read it from config, so a rename or retirement is one edit, not a redeploy hunt.
• Fail loudly at startup: call /v1/models once on boot and assert your configured model is present. A 404 at step 40 of an agent run is far more expensive than a clear failure at second zero.
• Treat model_not_found as terminal in retry logic — like insufficient_quota, retrying never fixes it.
• If your workload should survive one model being unavailable, that is an argument for selecting models at the routing layer rather than pinning one in code — what a router API should handle for you.

Part of the LLM API Error Reference — errors indexed by their exact strings.