Model Not Found: How to Diagnose and Fix the API Error

What to save before changing the configuration

First, record 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_...

API Key, full prompt and answer are not included in the card. If the error occurred in the IDE or agent tool, separately write down the name of the config file and the presence of environment variables. This will allow you to understand what value actually went to the server.

Would you like to repeat the diagnostics on the current catalog of models? You can create your own BetterToken account and API Key, check the endpoint and Model ID with API reference, and then run one minimal request. For BetterToken, the endpoint type, Base URL, Key group and current Model ID must match; take the current name from the documentation or models and prices page, and check the result in the Dashboard.

Step 1: Check Base URL and Path

Look at the final URL of the request, not just the line in the settings. The SDK can independently add /v1, /models, /chat/completions, /responses or /messages.

Typical mistakes:

• Base URL already contains the resource path, and the SDK adds it a second time;
• /v1 is missing or duplicated;
• The OpenAI client sends a request to the Anthropic-compatible address;
• the environment variable overrides the Base URL from the config;
• the application uses a different profile or workspace.

For BetterToken OpenAI-compatible, the tools use a Base URL with /v1, and Anthropic SDK and Claude Code use an address without /v1; the full Messages path is generated separately. Before correcting, check the current page of the specific tool.

Step 2: Check which API Key is actually being used

The same visual interface can store multiple credentials. A model error sometimes masks the lack of access of a selected key.

Check:

1. credential or environment variable from which the client reads the key;
2. no extra spaces or line breaks;
3. correspondence of the key to the protocol and group of models;
4. does the project config override the global setting;
5. whether the key has expired or been revoked.

Do not output the key via echo, debug log or screenshot. To compare credentials, a secure profile name or the last characters of a fingerprint are sufficient, if the interface itself shows them.

Step 3. Get the current Model ID

An OpenAI-compatible endpoint often has a list of models. A safe diagnostic request looks like this:

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

The command uses environment variables and does not contain the actual key in the text. It is only suitable when the endpoint documentation confirms /models.

For another protocol or client, use the provider's official directory. Copy the field id without changing case, spaces or suffixes. Marketing model name and API Model ID may vary.

If the list opens, but the desired model is not in it, check the selected key and catalog. If /models itself returns an error, first fix the endpoint or authorization.

Step 4: Find alias and legacy setting

Model ID can come from several places:

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

Searching the repository helps you find the old value:

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

The search may also find configuration files that contain secrets. Do not publish the full output. Correct only the source that the client reads.

AI tools often have a "project config over global config" priority. After the change, restart the client or open a new session if it caches provider settings.

Step 5: Separate the model error from the access error

HTTP codes for compatible APIs do not have to match, so look at the error body as well.

• 401: check the credential and authorization format first.
• 403: the model may exist, but the current key does not have access.
• 404: possible path, endpoint or Model ID.
• 400: The server may have rejected the model field or another request parameter.
• 429 / 5xx: this is usually a different category; do not change Model ID without an additional signal.

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

Minimum retest

After fixing, send one short request without streaming and tools. For OpenAI-compatible Chat Completions, the scheme might 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's documentation. Do not transfer this example to Anthropic Messages without adaptation.

A successful check consists of four matches:

• HTTP status means success;
• the response indicates the expected Model ID or its documented version;
• request appeared in Dashboard;
• time, status and usage match the test.

If the short query works and the IDE continues to show model not found, the server configuration has already been fixed. Look for override or cache inside the client.

Short checklist

• Status, provider code and request ID saved.
• Checked the final URL without double /v1 and resource path.
• The client uses the expected credential.
• Model ID taken from the current catalog.
• Project, global and environment override have been checked.
• One minimal request was executed without tools and stream.
• Request mapped to Dashboard.

For BetterToken, check API reference and current directory before replacing Model ID. It's faster and safer than searching through similar names.

FAQ

Why is the model visible on the site, but the API returns model not found?

There may be a different protocol, Key group, directory region, an outdated session, or a mismatch between the marketing name and the API ID. Check the list of models specifically for the current credential.

Will repeating the request help?

If there is a typo or incorrect endpoint - no. First fix the configuration. Retry is appropriate for a temporary error only when the status and provider code confirm this.

Is it possible to save the list of models in config forever?

Store the selected ID as a managed setting and check it against the current catalog from time to time. Availability and aliases can change.

Why does curl work but the application doesn't?

The application can read a different Base URL, credential or Model ID. Compare the final request and check the project-level override, environment variables and saved profile.