Claude API 404 "model not found" (not_found_error): Causes and Fixes

You call /v1/messages or /v1/chat/completions and get HTTP 404 with not_found_error or model_not_found. Here is what the error means, the handful of causes behind almost every case, and the exact commands to fix each one.

Quick answer

A 404 not_found_error means the model ID string in your request does not exist on the endpoint you called — the request is rejected at routing time, before any tokens are processed or billed. In practice it is almost always a spelling mismatch (claude-opus-4-8 vs claude-opus-4.8), a deprecated model ID, or a gateway that lists the model under a different alias. Fix it by copying the exact ID from GET /v1/models (or your provider's console model list) instead of typing it from memory.

Symptoms and What the Error Means

On Anthropic's native Messages API, the body looks like this:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "model: claude-opus-4.8"
  }
}

On an OpenAI-compatible endpoint, the same failure typically reads:

{
  "error": {
    "message": "The model `claude-opus-4-8-20260101` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}

Either way, the routing layer could not map your model string to a live model. Don't confuse it with two neighbors:

• 401 / authentication_error — your key is the problem, not the model.
• "No available channel" (gateway-specific) — the model name exists, but your token's group has no route to it. Different fix; see Common Errors.

A 404 is painless to debug: nothing ran, no tokens were consumed, and you can retry freely.

Why It Happens

1. Wrong separator or typo — a dot where the endpoint expects a hyphen (or vice versa), a missing tier, a transposed digit.
2. Missing or wrong date suffix — Anthropic's dated snapshots (-20250805 style) are exact strings; guessing a date produces a name that never existed.
3. The model was deprecated, retired, or renamed — old IDs eventually stop resolving.
4. Gateway alias mismatch — the gateway's catalog name differs from Anthropic's official ID, and you used the one from the wrong side.
5. Access scoping — some providers return 404 instead of 403 when your key lacks the model, so "not found" can also mean "not yours."

Fix 1: Check the Separator — Hyphen vs Dot

This is the single most common cause. Anthropic's official API replaces the version dot with a hyphen; many gateways expose a shorter alias with a literal dot.

Where you call	Naming style	Example
Anthropic API (dated snapshot)	hyphens + date suffix	claude-opus-4-1-20250805
Anthropic API (alias)	hyphens, no date	claude-opus-4-1
Typical gateway catalog	version with a dot	claude-opus-4.8

Two more traps in the same string:

• Tier position flipped with Claude 4. The Claude 3 era wrote version first (claude-3-7-sonnet-20250219); from Claude 4 onward the tier comes first (claude-opus-4-1).
• Never translate between styles by hand. claude-opus-4.8 on a gateway does not imply claude-opus-4-8 works on Anthropic, or the reverse.

Fix 2: List the Models Your Key Can Actually Use

Stop guessing — ask the endpoint. Both API families support GET /v1/models:

# Anthropic native
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

# OpenAI-compatible (gateway example)
curl https://byesu.com/v1/models \
  -H "Authorization: Bearer sk-YOUR_TOKEN"

Or filter with the OpenAI SDK:

from openai import OpenAI

client = OpenAI(api_key="sk-YOUR_TOKEN", base_url="https://byesu.com/v1")
for m in client.models.list():
    if "claude" in m.id:
        print(m.id)

Copy one ID from the output verbatim and run a minimal smoke test:

curl https://byesu.com/v1/chat/completions \
  -H "Authorization: Bearer sk-YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4.8",
    "messages": [{"role": "user", "content": "Reply with the single word: ok"}]
  }'

If the smoke test passes but your app still 404s, log the outgoing request body and compare the model field character by character — watch for trailing whitespace and smart quotes pasted from chat apps.

Fix 3: Rule Out Deprecation and Renames

Model IDs are not forever: the claude-2.x and claude-instant lines are long retired, claude-3-sonnet was retired in 2025, and claude-3-opus reached end of life in early 2026. If a previously working ID starts returning 404 with no code change, deprecation is the prime suspect.

What to do:

• Check Anthropic's model deprecation documentation for the announced retirement date of your ID.
• Migrate to the current family and re-run your evals — behavior differences matter more than the name change.
• Pin dated snapshots for reproducibility, but watch deprecation notices — a pinned date suffix dies quietly.

Fix 4: Mind the Gateway Mapping

A gateway sits between naming schemes, and its own catalog is the source of truth:

• A dated Anthropic snapshot (claude-opus-4-1-20250805) may not be listed even when the same model is available under a short alias.
• Code migrated from Anthropic-direct to a gateway (or the reverse) should re-resolve every model string against the new endpoint's /v1/models.
• If the gateway passes your model string through to an upstream verbatim, a name that looks right in docs can still 404 upstream — the list your own token returns is the only reliable reference.

If You're Calling Claude Through byesu

byesu is an AI API gateway with OpenAI-compatible and Anthropic-native endpoints — one key covers Claude, GPT-5.6, Grok, and Gemini, billed pay-as-you-go with no subscription. Two properties make this class of 404 easier to avoid:

• One catalog, both formats. The same model ID works on /v1/messages and /v1/chat/completions — copy the string once from the console model list or from GET /v1/models (scoped to your token's group) and reuse it everywhere, including ANTHROPIC_MODEL in Claude Code.
• Clearer error split. A true typo returns the model-not-found error above; a correct name in a token group without that model returns "no available channel" instead, so you know to fix the token's group, not the spelling. See Common Errors.

Getting started takes minutes: sign up, top up with USDT, Alipay or WeChat Pay, create a token, and verify your model string with the /v1/models call shown in Fix 2. Full setup: Quick Start.

FAQ

Why does the Claude API return 404 model not found?

A 404 not_found_error means the model string in your request does not exist on the endpoint you called; it is rejected before any tokens are processed. The usual causes are a typo (wrong separator, missing date suffix), a deprecated model, or a gateway that lists the model under a different alias than Anthropic's official ID.

What is the difference between claude-opus-4-8 and claude-opus-4.8?

Anthropic's official API uses hyphens everywhere — the version dot becomes a hyphen (claude-opus-4-8, often with a date suffix). Many gateways instead expose a short alias with a literal dot, such as claude-opus-4.8. Each one only works on the endpoint that defines it, so copy the exact ID from the model list of the service you are actually calling.

How do I list the models available to my API key?

Call GET /v1/models. On Anthropic's API, send your key in the x-api-key header plus the anthropic-version header; on an OpenAI-compatible endpoint, send Authorization: Bearer with your token. The response lists the exact model IDs your key can use — copy from there instead of typing from memory.

Was my Claude model deprecated or renamed?

Possibly. The claude-2.x and claude-instant lines are long gone, claude-3-sonnet was retired in 2025, and claude-3-opus reached end of life in early 2026. Naming also changed with Claude 4 — tier and version swapped positions (claude-3-7-sonnet became claude-opus-4-1 style). If an old ID suddenly returns 404, check Anthropic's deprecation page and migrate to a current model.

Why does a model work on the Anthropic API but return 404 on a gateway?

Gateways map official model IDs to their own catalog, and the alias can differ from Anthropic's dated ID — a snapshot like claude-opus-4-1-20250805 may not be listed even when the same model is available under a shorter alias. Query the gateway's GET /v1/models or console model list and use the string shown verbatim.