model_not_found is one of the most misleading errors in OpenAI-compatible API work.
It often looks like a provider outage or SDK bug, but the root cause is usually more boring:
- the model ID belongs to a different gateway;
- the base URL points to another provider;
- the API key is from the wrong workspace;
- the model alias changed;
- the account does not have access to that model;
- a fallback route is hiding the real failure;
- the SDK is sending a model name that was copied from docs for a different platform.
Here is the debugging checklist I use before changing application code.
1. Confirm the base URL first
Do not start with the model name.
Start with the endpoint.
If your SDK is configured for an OpenAI-compatible gateway, the base URL usually needs to end in a versioned API path such as /v1.
Small differences matter:
- direct provider endpoint;
- gateway endpoint;
- local proxy endpoint;
- staging endpoint;
- production endpoint.
If the base URL points to the wrong place, a correct model ID can still fail.
2. Pair the API key with the same gateway
Base URL and API key should be treated as one pair.
Do not mix:
- an OpenAI key with a third-party gateway base URL;
- a gateway key with a direct provider URL;
- a staging key with production models;
- a personal key with a team model directory.
If the key belongs to another account context, the model may look nonexistent even when it is available somewhere else.
3. Copy the exact model ID from the current model directory
Model display names are not always API model IDs.
For example, a UI might say "Claude Haiku" or "GPT mini", while the actual API ID includes a provider prefix, version, or suffix.
Before testing, copy the exact model ID from the same platform you are sending the request to.
TackleKey's model directory is built around this practical step: 216 OpenAI-compatible model IDs, current input/output reference pricing, and a small cURL example for each model family.
Model directory: https://tacklekey.com/models
4. Test with the smallest possible request
Before debugging LangChain, Vercel AI SDK, custom agent loops, streaming, tools, or RAG code, test one minimal request.
The goal is to isolate three values:
- base URL;
- API key;
- model ID.
Once those work together, copy the same values into the application runtime.
Examples: https://tacklekey.com/examples
5. Check logs before changing providers
If you have request logs, check:
- which exact model ID was received;
- whether the request reached the gateway;
- whether the account had model access;
- whether a fallback route was attempted;
- the returned status and error code.
If logs are missing, you are guessing.
6. Do not use price pages as model ID docs
Pricing tables are useful, but they are not always a source of copy-ready model IDs.
For production work, you want the model directory, examples, request logs, and pricing view to agree with each other.
That is the boring part that prevents a lot of model_not_found errors.
Quick Rule
When model_not_found appears, do not ask "which model is down?"
Ask:
Did this exact API key call this exact model ID through this exact base URL before?
If the answer is no, reduce the test until those three values are proven together.
Top comments (0)