OpenAI model_not_found: check model ID, access and endpoint

An OpenAI model_not_found response means you need to check the requested model, access and API route together. A 404 status alone does not identify the cause. Save the full error body and request ID before changing credentials, models or billing settings.

This guide was checked against OpenAI’s API error documentation on September 16, 2026.

If your error explicitly names GPT-5.5 inside Codex, start with the GPT-5.5 Codex 404 checklist. This page is the diagnostic hub for model IDs, endpoints, project permissions and provider routing across clients.

First identify which 404 you are seeing

If the browser itself displays a generic 404, start with the browser resource. If a developer tool displays an API error, capture its underlying response rather than diagnosing from the window title.

Read the error body before retrying

A model-related error can look like this illustrative response:

{
  "error": {
    "message": "The model `MODEL_ID` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

The two alternatives in that message matter. It does not tell you which applies. Nor does it establish an official motive for returning 404 instead of another status. Authentication, permission, missing resources and malformed requests must be diagnosed using the full response and the endpoint documentation.

Record the timestamp, host, path, exact model string, project context and request ID. Never copy the secret API key into a support ticket or a public issue.

Check the exact model ID and account context

Compare the model string with the provider’s current model documentation. Check punctuation, family suffixes and dated versions. A product’s display name is not necessarily an API ID.

For the direct OpenAI API, inspect the model list using the same key and project context as the failing request:

# Direct OpenAI only. Keep the key out of shell history and shared logs.
: "${OPENAI_API_KEY:?Set the key for the failing OpenAI project first}"
curl --silent --show-error --fail-with-body \
  --dump-header model-list-headers.txt \
  --output model-list.json \
  https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

This read-only model-list request does not generate an answer. If the failing application explicitly sets an organization or project header, reproduce that same authorized context as well. Do not add a guessed project, and do not run this direct-OpenAI example with another provider’s key. Keep the saved headers and body private until reviewed for sensitive information.

For a successful JSON listing, this local check tests an exact ID without running inference. Replace the placeholder with the ID from the failed request:

MODEL_ID='replace-with-the-exact-requested-model-id' python3 - <<'PYCODE'
import json
import os
from pathlib import Path

payload = json.loads(Path("model-list.json").read_text())
if not isinstance(payload.get("data"), list):
    raise ValueError("Expected a successful model listing; inspect the error body first")
ids = {item["id"] for item in payload["data"] if isinstance(item, dict) and "id" in item}
print("listed" if os.environ["MODEL_ID"] in ids else "not listed")
PYCODE

A listing is evidence about that request’s context. It is not a complete proof of permission to use every operation or a reason to replace keys at random.

The models API reference describes the listing. Use it as diagnostic evidence alongside the model and endpoint documentation. A listing is not a guarantee that every endpoint, tool, modality or account configuration will work with that model.

If access is missing, check the project’s permissions and the documented eligibility requirements. OpenAI exposes project model permissions to authorized administrators. A regular application key should not be replaced with an admin key just to run inference; ask the project owner to verify the relevant policy. Do not infer a universal spending threshold, waiting period or instant access guarantee. A provider switch is a separate integration decision and does not automatically resolve access restrictions or legal availability.

Match the model to the endpoint

A text model, image model and tool-specific model may require different request shapes. Check the model page and the endpoint you intend to call. For example, an image-generation tool inside Responses is not identical to a direct Images API call.

The GPT Image 2.5 API guide shows that distinction for image generation. It does not mean that every 404 is caused by using the wrong API family.

For custom providers, check for a duplicated /v1 segment, a wrong host, or an unsupported route. Do not test a gateway key against OpenAI’s host or an OpenAI key against an unrelated gateway.

Check retirement and deployment configuration

A previously working model may have been retired or replaced. Do not guess a replacement by changing a version digit or appending a date. Check the official deprecations page and the provider’s own notice. Follow the documented replacement and verify parameter compatibility rather than changing only a name.

For Azure, compare the deployment name in the request with the deployment in the correct resource. Check the API version and route against the documentation for that Azure API surface. Do not apply the standard OpenAI URL pattern to every Azure integration.

For Batch, inspect the failed request, its endpoint and the model’s documented Batch support. Do not invent a hidden -batch snapshot name or assume a model available synchronously is supported in every asynchronous workflow.

A short diagnostic sequence

1. Separate a website-resource 404 from an API response.
2. Save the complete error and request ID.
3. Confirm the actual host, endpoint, model string and account/project.
4. Compare model availability and endpoint support with current documentation.
5. Check retirement notices or Azure deployment configuration where applicable.
6. After correcting the cause, send a minimal request using the same account context. Such an inference request may be billable.

Repeatedly sending an unchanged request is unlikely to resolve a persistent wrong ID or missing deployment. For a temporary service problem, use the provider’s status and retry guidance rather than assuming a permanent configuration error.

When the error is inside Codex

Inspect the effective provider and configuration before replacing keys. The Codex config.toml guide explains file locations, profiles and override order. The Codex error index helps distinguish startup, authentication and API failures.

If the request specifically names GPT-5.5, the GPT-5.5 Codex checklist applies to that model. A general 404 article should not be treated as evidence that every older or newer model has the same access rules.

Before escalating

Provide the request ID, time, error body, endpoint, model ID and redacted minimal example. Explain whether the same setup ever worked and which change preceded the failure. These details help distinguish a configuration issue from an account or service issue without exposing credentials.