model not found: Five Causes and How to Tell Them Apart in Two Minutes
Nine times out of ten the model was not retired — the name, the endpoint, or the entitlement does not line up. One request narrows it down immediately.
Always start by listing the models
Nearly every OpenAI-compatible endpoint exposes `GET /v1/models`. Call it **with the key and base_url you are actually using**, then compare the returned list against your model string character by character. It takes under a minute and eliminates three of the most common causes at once — because in all three, the name you want simply will not appear in that list.
The base_url trap: that trailing /v1
This is the single most asked question. Some providers expect base_url to end in `/v1`, others append it for you. The failure is deceptive: you do not get a 404, you get **model not found** — because the request reached a path that exists but does not know that model. **Print the full outgoing URL and look at it.** Do not trust what the config file says it should be.
Official names and provider codes may both work, or only one
When calling through a gateway, a model can have two usable names: the vendor's official name (`claude-sonnet-5`) and the gateway's own code. Some accept both, some only one. **Do not assume — one look at the docs or the model list settles it.** cocodot accepts both: official names and codes (such as `mcs-6`) route to the same model. The full list is at cocodot.co/pricing#models, machine-readable at `GET https://cocodot.co/api/ai/models`.
If every model reports not found, it is the endpoint
When several different model names all fail, the problem is not the names. It is almost always the base_url, the auth header, or the request path — the request is not arriving where you think. Verify connectivity with the simplest model and shortest possible body first, then come back to the model name. **Solve reachability before you solve the specific model**; doing it the other way round wastes a lot of time.
When it really was retired
Models do get retired, particularly previews and dated snapshots. Check the vendor's release notes to confirm. If so, the only option is a different model — which is where an OpenAI-compatible endpoint pays off: switching is one string, not a re-integration.
Five causes, and how to confirm each
| Cause | What it looks like | How to confirm |
|---|---|---|
| Name or suffix wrong | Another model name works fine | Pull /v1/models and compare exactly |
| base_url points elsewhere | Every model reports not found | Print the actual request URL |
| Model not enabled | Other models work, this one does not | Check the provider console |
| Alias not accepted there | Official name works but code does not, or vice versa | Read the provider's naming docs |
| Genuinely retired | Announced by the vendor | Check the vendor's release notes |