DEV Community

Alex Shcoder?
Alex Shcoder?

Posted on Originally published at model.sale

OpenAI API "model not found": 5 causes and a 30-second checklist

#openai #api #python #debugging

"The model does not exist or you do not have access to it" almost never means the model is gone. It means this request, with this key, sent to this URL, named an ID the server cannot call. Here is how to find out which part is wrong.

The error is an HTTP 404 with the code model_not_found. Do not confuse it with its neighbours:

Status and code Meaning
401 invalid_api_key the key is wrong
403 model_not_allowed the key is restricted to other models
404 on a path like /v1/response a typo in the endpoint, not the model
404 model_not_found this guide

1. Copy the ID from the list, not from memory

IDs are exact strings: lowercase, hyphens, no spaces. Ask the server what it can call:

curl https://api.example.com/v1/models -H "Authorization: Bearer $API_KEY"
Enter fullscreen mode Exit fullscreen mode

Aggregators often add a vendor prefix such as openai/gpt-6-sol; a name copied from one service's example fails on another.

2. The model may be temporarily unavailable

If a service routes to upstream capacity, a model can disappear from /v1/models while its health checks fail and return this same 404. If it worked yesterday and is missing from the list today, that is the cause, not a typo. Switch to a sibling model and retry later. Also keep the ID in one config value: hard-coded IDs in old tutorials keep failing after a rename.

3. Check the key's allowed models

A scoped key can carry an allow-list. Some clients surface model_not_allowed as "model not found". One project works and another does not? Compare their keys.

4. Make sure the client really uses your base URL

The classic trap: you changed the base URL, the tool still talks to its default endpoint, which does not know your model.

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.example.com/v1", api_key=os.environ["API_KEY"])
print(client.base_url)                      # what the client really uses
print([m.id for m in client.models.list().data][:10])
Enter fullscreen mode Exit fullscreen mode

Official SDKs read OPENAI_BASE_URL, older wrappers such as LangChain read OPENAI_API_BASE, and editors like Cursor keep their own model list, so add the custom model name there too.

5. Match the endpoint to the model

Models support /v1/responses, /v1/chat/completions or both. A client that only speaks Chat Completions can fail on a Responses-only model.

The 30-second checklist

  1. Read the status and error code.
  2. GET /v1/models with the same key: is the ID there, character for character?
  3. Which models is the key allowed to call?
  4. Does the request really reach the base URL you set (SDK debug log or curl -v)?
  5. Retry with a tiny prompt such as "Say hello".

If the ID is listed, the key allows it, the URL is right and you still get 404, keep the request ID from the response headers and contact the provider's support. Do not paste keys or prompts into the ticket.

I build Model.sale, a prepaid OpenAI-compatible API gateway. The checklist applies to any such service; our version with setup notes for Cursor, Codex CLI and Aider is here: https://model.sale/blog/model-not-found-error-openai-api

Top comments (0)