A model not found error means the server could not resolve the requested Model ID for the current endpoint and API Key. The cause may be a typo, retired alias, wrong protocol, missing access, or a client-side override. Record the status and request ID, then work from the Base URL toward the credential and model. Guessing similar model names hides the original fault.

Preserve Evidence Before Changing Configuration

Start with a small diagnostic card:

time: 2026-08-03T12:00:00Z
client: your-client-and-version
protocol: openai-compatible | anthropic-compatible
base_url: https://example.com/v1
model: MODEL_ID_FROM_CONFIG
http_status: 404
provider_code: model_not_found
request_id: req_...

Do not include the API Key, full prompt, or response. If the error appeared in an IDE or agent tool, record the configuration file and whether environment variables are present. This helps establish which value was actually sent.

Want to repeat the diagnosis against the current model catalog? You can create your own BetterToken account and API key, compare the endpoint and Model ID with the API reference, and send one minimal request. For BetterToken, the endpoint type, Base URL, key group, and current Model ID must match; use the documentation or models and pricing page for the current name, then verify the result in the Dashboard.

Step 1: Check the Base URL and Final Path

Inspect the final request URL, not only the value in settings. An SDK may append /v1, /models, /chat/completions, /responses, or /messages itself.

Common mistakes include:

the Base URL already contains a resource path that the SDK appends again;
/v1 is missing or duplicated;
an OpenAI client is calling an Anthropic-compatible address;
an environment variable overrides the config file;
the application uses a different profile or workspace.

For BetterToken, OpenAI-compatible tools use a Base URL ending in /v1, while Anthropic SDK and Claude Code use the address without /v1; the complete Messages path is assembled separately. Verify the current guide for the specific tool before editing values.

Step 2: Check Which API Key Is Actually Used

One interface may store several credentials. A model error can sometimes mask missing access on the selected key.

Check:

the credential or environment variable read by the client;
leading or trailing whitespace;
whether the key matches the protocol and model group;
whether project configuration overrides the global setting;
whether the key was revoked or expired.

Do not print the key with echo, a debug log, or a screenshot. A safe profile name, or a fingerprint that the interface already displays, is enough to distinguish credentials.

Step 3: Retrieve the Current Model ID

An OpenAI-compatible endpoint often exposes a model list. A safe diagnostic request looks like this:

curl "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

The command uses environment variables and contains no literal key. Run it only when the endpoint documentation confirms /models.

For another protocol or client, use the provider's official catalog. Copy the id field exactly, including case and suffixes. A marketing name and an API Model ID may differ.

If the list works but does not contain the desired model, inspect the selected key and catalog. If /models itself fails, fix the endpoint or authentication first.

Step 4: Find an Alias or Stale Setting

The Model ID may come from:

project configuration;
global client configuration;
an environment variable;
a UI profile;
a command-line flag;
a saved session;
gateway routing or model mapping.

Search the repository for an old value:

rg -n --hidden --glob '!node_modules' --glob '!.git' \
  'OLD_MODEL_ID|model[[:space:]]*=' .

The command may find sensitive configuration files. Do not publish its complete output. Change only the source that the client really reads.

AI tools often give project configuration precedence over global configuration. Restart the client or open a new session after the change if provider settings are cached.

Step 5: Separate a Missing Model from Missing Access

Compatible APIs do not have to use identical status codes, so inspect the error body as well.

401: check the credential and authentication format first.
403: the model may exist, but the current key lacks access.
404: the path, endpoint, or Model ID may be wrong.
400: the server may have rejected model or another request field.
429 / 5xx: usually a different category; do not change the Model ID without another signal.

The phrase model not found in a UI may be the client's summary. Find the original HTTP status, provider code, and request ID.

Run One Minimal Retest

After the correction, send one short request without streaming or tools. An OpenAI-compatible Chat Completions check may look like this:

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_CURRENT_CATALOG",
    "messages": [{"role": "user", "content": "Reply with OK"}],
    "max_tokens": 8
  }'

The fields and endpoint must match your provider documentation. Do not copy this request into Anthropic Messages without adapting it.

A successful check has four matching signals:

the HTTP status indicates success;
the response reports the expected Model ID or a documented resolved variant;
the request appears in the Dashboard;
time, status, and usage match the test.

If the short request works but the IDE still reports model not found, the server-side values are now valid. Look for an override or cache inside the client.

Short Checklist

Status, provider code, and request ID are saved.
The final URL has no duplicate /v1 or resource path.
The client uses the expected credential.
The Model ID comes from the current catalog.
Project, global, and environment overrides are checked.
One minimal request ran without tools or streaming.
The request was matched with the Dashboard.

For BetterToken, check the API reference and current catalog before replacing a Model ID. This is safer and faster than guessing nearby names.

FAQ

Why is a model visible on a website while the API returns model not found?

The protocol, key group, catalog region, saved session, or API ID may differ. Check the model list for the exact credential being used.

Will retrying help?

Not for a typo or wrong endpoint. Fix the configuration first. Retry only when the status and provider code indicate a temporary failure.

Can I keep a model list in configuration forever?

Treat the selected ID as managed configuration and periodically compare it with the current catalog. Availability and aliases change.

Why does curl work while the application fails?

The application may read a different Base URL, credential, or Model ID. Compare the final request and inspect project overrides, environment variables, and saved profiles.

Model Not Found in an API: How to Locate and Fix the Cause