Claude Model Version Not Found: Falsche Model-IDs, Aliase und API-Routen beheben
Wenn Sie einen Fehler Claude model version not found sehen, ändern Sie nicht zuerst den Prompt. Beweisen Sie zunächst drei Dinge: Die Model-ID existiert heute, Ihr Endpunkt erwartet genau dieses ID-Format, und der Workspace oder Router, den Sie verwenden, darf den Aufruf ausführen.
Die schnelle Lösung ist meist eine von diesen:
| Prüfung | Was normalerweise kaputt war | Behebung |
|---|---|---|
| Model-ID | Ein veralteter fest codierter Claude-Snapshot, ein Tippfehler oder ein von einem anderen Provider kopierter Modellname | Ersetzen Sie ihn durch einen aktuellen Claude-API-Alias wie claude-sonnet-5-5, claude-opus-5-5, claude-haiku-5-5 oder claude-fable-5-1, nachdem Sie die aktuelle Anthropic-Modellliste geprüft haben. |
| Endpoint-Vertrag | Eine Bedrock-, Vertex-, Azure-, OpenAI-kompatible oder gateway-spezifische ID wurde an die falsche API gesendet | Passen Sie den Modellstring an den Endpunkt an, den Sie aufrufen. |
| Base URL | Das SDK zeigt auf die falsche base_url, den falschen Pfad oder die falsche Route |
Bestätigen Sie, ob der Client das Anthropic-native /v1/messages oder eine OpenAI-kompatible Route verwendet. |
| Zugriff | Das Modell existiert, aber Ihr Workspace, Provider-Konto oder Sub-Key darf es nicht verwenden | Prüfen Sie Workspace-Berechtigungen, Allowlists und den Modellzugriff, bevor Sie es erneut versuchen. |
| Rollout-Status | Ein neu angekündigtes Modell ist in der Dokumentation sichtbar, aber noch nicht in Ihrem Router oder Deployment vorhanden | Führen Sie einen Canary-Test für die Route durch und behalten Sie das zuvor funktionierende Modell bei, bis die neue Route bestanden hat. |
Dieser Leitfaden bietet Ihnen ein praktisches Runbook für claude model version not found, claude model version und claude model versions-Fehler in Produktions-Apps, Claude-Code-Setups, Gateways und Agenten-Infrastruktur.
Was „Claude model version not found“ bedeutet
Claude model version not found ist in der Regel eine Integrationsbeschreibung eines Fehlers bei der Modellauflösung. Direkte Anthropic-API-Fehler sind als strukturierte JSON-Fehler aufgebaut. Anthropic dokumentiert 404 - not_found_error für eine angeforderte Ressource, die nicht gefunden werden kann, und die Fehlerkörper enthalten einen error.type, error.message und eine Request-ID. Die Messages API von Anthropic erfordert außerdem ein model-Feld, das das Modell benennt, das den Prompt vervollständigt.
Diese Unterscheidung ist wichtig. Eine direkte API-Antwort, eine SDK-Exception, ein Gateway-Wrapper und eine Agent-CLI können denselben zugrunde liegenden Fehler unterschiedlich formulieren. Ihre Aufgabe ist es, den Roh-Statuscode, error.type, message, Request-ID, Modellstring, Endpunktpfad und die Base URL zu erhalten, bevor Sie es erneut versuchen.
Verwenden Sie diese Triage-Regel:
- 404 /
not_found_error: Prüfen Sie zuerst den Endpunktpfad, die Modellkennung und die Ressourcen-IDs. - 400 /
invalid_request_error: Prüfen Sie, ob das Modell existiert, aber eine Einstellung, einen Tool-Typ, einen Thinking-Modus, ein Prefill oder die Anfrageform ablehnt. - 401 / 403: Prüfen Sie Authentifizierung, Workspace-Zugriff und Modellberechtigungen.
- Gateway-spezifisch „model version not found“: Prüfen Sie sowohl den Gateway-Modellkatalog als auch die Upstream-Provider-ID, auf die er abbildet.
Prüfung der aktuellen Claude-Modell-ID
Vergleichen Sie vor dem Bearbeiten von Code den fehlschlagenden Modellstring mit der aktuellen offiziellen Liste. Zum Zeitpunkt der für diesen Artikel geprüften aktuellen Anthropic-Modelldokumentation umfassen die sichtbaren Claude-API-Aliase:
| Familie | Zu prüfender Claude-API-Alias |
|---|---|
| Fable | claude-fable-5-1 |
| Opus | claude-opus-5-5 |
| Sonnet | claude-sonnet-5-5 |
| Haiku | claude-haiku-5-5 |
Nehmen Sie nicht an, dass ein Modellname aus einem Blogbeitrag, einem UI-Label, einem Provider-Marktplatz oder einem älteren Codebeispiel für jede API-Oberfläche gültig ist. Die Dokumentation von Anthropic zeigt separate IDs für Claude API, Amazon Bedrock, Google Cloud, Microsoft Foundry und Claude Platform on AWS. Diese IDs können ähnlich aussehen, sind aber nicht austauschbar.
Sechs häufige Ursachen
1. Eine veraltete fest codierte Claude-Modellversion
Fest codierte Modell-IDs altern schlecht. Ein Dienst kann noch einen älteren Snapshot enthalten wie:
const model = "claude-3-7-sonnet-20250219";
Wenn der Endpunkt diesen Snapshot nicht mehr akzeptiert oder Ihr Router ihn nie gemappt hat, kann die Anfrage fehlschlagen, bevor der Prompt ausgewertet wird. Ersetzen Sie den fest codierten Wert durch einen aktuellen Alias, den Ihr Endpunkt unterstützt, und speichern Sie diesen Alias dann in einer einzigen Konfigurationsquelle statt verstreut in Dateien.
const model = process.env.CLAUDE_MODEL ?? "claude-sonnet-5-5";
Für Produktionssysteme protokollieren Sie sowohl den konfigurierten Alias als auch die aufgelöste Route. So wird der nächste Vorfall Claude model version not found zu einem Konfigurations-Diff statt zu einer Codesuche.
2. Eine provider-spezifische ID wurde an die Claude-API gesendet
Provider-Plattformen verwenden ihre eigenen Modellkennungen. Eine Bedrock-ähnliche oder Vertex-ähnliche ID kann auf diesem Provider gültig und gegenüber der nativen Claude-API ungültig sein. Umgekehrt gilt dasselbe: Ein nativer Claude-API-Alias ist möglicherweise nicht die vollständige Kennung, die von einer Cloud-Provider-Runtime erwartet wird.
Verwenden Sie diese Tabelle zum Endpoint-Vertrag:
| Sie rufen auf | Die Model-ID sollte so aussehen | Vermeiden |
|---|---|---|
Anthropic Claude API /v1/messages |
Claude-API-Alias aus der Anthropic-Dokumentation, zum Beispiel claude-sonnet-5-5 |
Bedrock-, Vertex- oder mit Foundry-Präfix versehene IDs |
| Amazon Bedrock | Bedrock-Model-ID, wie sie in den Anbieter-Dokumenten oder in der Konsole angezeigt wird | Nativ nur für Claude gedachte Aliase, wenn das SDK Bedrock-IDs erwartet |
| Google Cloud / Vertex | Google-Cloud-Model-ID, die für diese Bereitstellung angezeigt wird | Native oder Bedrock-IDs, die aus einer anderen Umgebung eingefügt wurden |
| OpenAI-kompatibler Router | Die Model-Katalog-ID des Routers | Native Anthropic-Request-Strukturen, sofern der Router sie nicht ausdrücklich unterstützt |
| Flatkey-Router | Eine von Flatkey unterstützte Route aus dem Flatkey-Modelkatalog oder den Einrichtungsanweisungen | Verstreute Provider-Keys und ungeprüfte Überschreibungen pro Agent |
Wenn sich Ihre Bereitstellung über direktes Anthropic, Endpunkte von Cloud-Anbietern und einen Router erstreckt, halten Sie in der Konfiguration eine kleine Übersetzungstabelle vor:
routes:
claude_primary:
api_surface: anthropic_messages
model: claude-sonnet-5-5
claude_gateway:
api_surface: openai_compatible_router
model: claude-sonnet-5-5
claude_bedrock:
api_surface: bedrock
model: anthropic.claude-sonnet-5-5
Die genauen Zeichenfolgen müssen von dem Provider oder Router stammen, den Sie verwenden. Der Punkt ist, die API-Oberfläche explizit zu machen.
3. Basis-URL und SDK stimmen nicht überein
Das Anthropic-SDK erwartet den Vertrag der Anthropic Messages API. Ein OpenAI-kompatibler Router erwartet einen OpenAI-kompatiblen Client und Payload, sofern nicht eine Anthropic-kompatible Route dokumentiert ist. Wenn Client, Pfad und Model-Feld vermischt sind, kann der Fehler wie eine fehlende Claude-Model-Version aussehen, selbst wenn das eigentliche Problem die falsche Route ist.
Prüfen Sie diese Felder gemeinsam:
SDK/Client: Anthropic SDK, OpenAI SDK, Claude Code, Cursor, Cline, Custom HTTP
Basis-URL: direkter Provider, Router, Staging-Proxy, lokaler Mock
Pfad: /v1/messages, /v1/chat/completions, provider-spezifischer Runtime-Pfad
Model-ID-Format: nativer Claude-Alias, Cloud-Provider-ID, Router-Katalog-ID
Auth-Header: x-api-key, Authorization: Bearer, provider-spezifische Signierung
Wenn eine Zeile zu einer anderen API-Oberfläche gehört, beheben Sie das vor dem erneuten Versuch.
4. Ein neuer Claude-Alias ist noch nicht bei Ihrem Router angekommen
Model-Starts erfolgen nicht atomar über jedes SDK, jeden Proxy, jeden Cloud-Provider und jedes Gateway hinweg. Ein Modell kann in einem Katalog erscheinen, bevor Ihre Route, Allowlist oder Bereitstellung es unterstützt.
Verwenden Sie ein Canary-Deployment, statt den Produktionsverkehr sofort umzustellen:
model_canary:
candidate_model: claude-sonnet-5-5
previous_model: claude-sonnet-5
checks:
- minimale Anfrage ohne Streaming
- Streaming-Anfrage, wenn Ihre App streamt
- Tool-Call-Anfrage, wenn Ihre App Tools verwendet
- Token-Count- oder Dry-Run-Pfad, falls verfügbar
- Abrechnungs- und Nutzungs-Ledger-Zeile
rollout:
start: 1%
promote_when: 100 erfolgreiche Anfragen und keine Model-Resolution-Fehler
rollback_on: jeder wiederholte not_found_error oder Route-Mismatch
Hier helfen Flatkeys Routing- und Ledger-Ansicht. Wenn Claude nur eine Route unter vielen Modellen ist, verwenden Sie einen Model-Katalog, eine Basis-Route-Prüfung und ein Nutzungs-Ledger, statt separate Provider-Konsolen und separate Agenten-Konfigurationen zu debuggen.
5. Workspace-Berechtigungen oder Model-Allowlists blockieren den Zugriff
Manchmal ist die Model-Zeichenfolge gültig, aber Ihr Key kann sie nicht aufrufen. Das kann auf Ebene des Provider-Workspaces, des Cloud-Kontos, des Routers oder eines Sub-Keys passieren.
Prüfen Sie:
- Ob der API-Key zu dem Workspace gehört, den Sie erwarten.
- Ob das Modell für diesen Workspace aktiviert ist.
- Ob ein Gateway-Sub-Key, Umgebungs-Key oder Agent-Key eine Model-Allowlist hat.
- Ob Staging- und Produktions-Keys unterschiedliche Model-Zugriffe haben.
- Ob Ausgabenlimits oder Richtlinienkontrollen einen berechtigungsähnlichen Fehler zurückgeben.
Lösen Sie Zugriffsfehler nicht, indem Sie jeden Key großzügiger machen. Erstellen Sie eine eng gefasste Richtlinie, die festlegt, welche Agenten und Umgebungen jede Claude-Model-Version aufrufen dürfen.
6. Das Modell existiert, aber Ihre Anfrage verwendet nicht unterstützte Model-Features
In den Fehlerdokumenten von Anthropic werden mehrere Validierungsfehler aufgeführt, bei denen das Modell real ist, aber die Anfrageform ungültig ist. Beispiele sind Unterschiede im Thinking-Modus, erzwungene Tool-Use-Einstellungen, Unterstützung von Tool-Typen und vorab ausgefüllte Assistant-Nachrichten bei neueren Modellen.
Wenn der Status 400 invalid_request_error ist, suchen Sie nicht weiter nach einer fehlenden Model-Version. Vergleichen Sie stattdessen den Request-Body mit den aktuellen Fähigkeitsregeln des Modells. Die Lösung kann darin bestehen, thinking, tool_choice, Tool-Deklarationen oder das Handling des Nachrichtenverlaufs zu ändern, statt model zu ändern.
Ein Debug-Runbook für die Produktion
Schritt 1: Erfassen Sie den vollständigen fehlgeschlagenen Request-Datensatz
Speichern Sie einen minimalen Debug-Datensatz, bevor Sie etwas ändern:
{
"provider": "anthropic_or_router_name",
"base_url": "https://api.example.com",
"path": "/v1/messages",
"model": "claude-sonnet-5-5",
"sdk": "anthropic-typescript",
"status": 404,
"error_type": "not_found_error",
"request_id": "req_...",
"environment": "production",
"api_key_scope": "prod-agent-key"
}
Wenn Sie Flatkey verwenden, erfassen Sie auch die Route, den Sub-Key, die Zeile im Usage-Ledger und jede Fallback-Entscheidung. Wenn Sie direkt Anthropic verwenden, behalten Sie den Wert request-id aus der Antwort, da Anthropic diese Kennung in Supportfällen anfordert.
Schritt 2: Mit der kleinsten Anfrage reproduzieren
Entfernen Sie Tools, langen Verlauf, Bilder, zwischengespeicherte Thinking-Blöcke und Framework-Wrapper. Testen Sie eine kurze Nachricht mit genau demselben Modell und Schlüssel.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 64,
"messages": [
{"role": "user", "content": "Reply with ok."}
]
}'
Wenn die minimale Anfrage funktioniert, existiert die Modellversion für diesen Schlüssel und dieses Endpunkt. Gehen Sie zum Debugging der Anfrageform über. Wenn sie mit demselben Not-found-Ergebnis fehlschlägt, konzentrieren Sie sich auf die Modellzeichenfolge, den Endpunkt oder die Zugriffsschicht.
Schritt 3: Modell-IDs an einer Stelle normalisieren
Erstellen Sie eine einzelne Konfigurationsquelle für Claude-Modellversionen:
models:
claude_default:
owner: platform
api_surface: anthropic_messages
model: claude-sonnet-5-5
fallback: claude-haiku-5-5
last_verified: "2026-10-10"
claude_reasoning:
owner: agents
api_surface: anthropic_messages
model: claude-opus-5-5
fallback: claude-sonnet-5-5
last_verified: "2026-10-10"
Blockieren Sie dann rohe Modell-IDs im Anwendungscode. Die App sollte claude_default anfordern, statt eine neue Claude-Modellversion in fünf Services einzufügen.
Schritt 4: Agenten- und CI-Konfiguration prüfen
Fehler vom Typ „Claude model version not found“ entstehen oft durch eine vergessene Umgebungsvariable statt durch eine Codeänderung. Prüfen Sie:
.env,.env.productionund Werte im Secret Manager.- Claude Code, Cursor, Cline, Roo, Aider und GitHub-Actions-Variablen.
- Standardwerte in Docker-Images und Kubernetes-Config-Maps.
- Modell-Allowlists pro Kunde oder Team-Sub-Key.
- Lokale Entwicklungs-Overrides, die in die Produktion kopiert wurden.
Wenn Ihr Team Claude Code über ein Gateway verwendet, prüfen Sie auch die Auth- und Base-URL-Konfiguration. Eine fehlerhafte ANTHROPIC_BASE_URL oder ein falscher Key-Scope kann die Modeldiagnose unübersichtlich machen; verwenden Sie den Leitfaden zu Claude Code Auth Token Errors, wenn auch die Authentifizierung fehlschlägt.
Schritt 5: Entscheiden, ob erneut versucht, gefallbackt oder hart abgebrochen werden soll
Wiederholen Sie einen deterministischen Missing-Model-Fehler nicht endlos. Verwenden Sie diese Richtlinie:
| Fehlermuster | Retry? | Fallback? | Aktion durch Menschen |
|---|---|---|---|
| Tippfehler oder veraltete Modell-ID | Nein | Nur nachdem die Konfiguration korrigiert wurde | Modell-Registry aktualisieren und neu deployen |
| Neuer Alias noch nicht im Router | Keine wiederholten Retries | Vorher verifiziertes Modell beibehalten | Route-Freischaltung/Canary-Task öffnen |
| Workspace hat keinen Zugriff | Nein | Vielleicht, wenn ein genehmigter Fallback vorhanden ist | Key, Workspace oder Allowlist korrigieren |
| 400 Request-Shape-Mismatch | Nein | Nicht, bevor die Anfrage korrigiert ist | Request-Body oder Feature-Flags patchen |
| 529 überlastet oder vorübergehender Upstream-Ausfall | Ja, begrenztes Backoff | Ja, wenn die Fallback-Richtlinie dies erlaubt | Route-Health überwachen |
Für die Behandlung vorübergehender Überlastung verwenden Sie ein anderes Runbook: API Error 529 overloaded. Ein Fehler bei der Modellversion ist in der Regel deterministisch, bis Sie die Konfiguration ändern.
Flatkey-Checkliste für die Routenprüfung
Wenn Claude Teil eines Multi-Model-Systems ist, gibt Ihnen ein Router einen Ort, an dem Sie Modellnamen, Schlüssel, Allowlists, Ausgaben und Fallbacks prüfen können. Die Positionierung von Flatkey ist: ein Schlüssel, ein Kontostand, eine Rechnung, offizielle Modellendpunkte und ein gemeinsames Usage-Ledger über Modelle und Tools hinweg.
Verwenden Sie diese Checkliste, bevor Sie eine neue Claude-Route freigeben:
route_review:
route_name: claude_primary
current_model: claude-sonnet-5-5
endpoint_contract: openai_compatible_or_anthropic_native
owner: platform
environments:
dev: verified
staging: verified
production: canary
controls:
sub_key_allowlist: true
request_ledger: true
fallback_policy: explicit
usage_alert: true
rollback:
previous_model: claude-sonnet-5
trigger: repeated model-resolution errors
Für ein breiteres Routendesign lesen Sie Claude API proxy vs multi-model router und den AI model catalog guide. Für Kosten- und Routing-Abwägungen kombinieren Sie diesen Artikel mit Claude API pricing und LLM API fallback routing.
Kopierbare Incident-Checkliste
Verwenden Sie dies in Slack, Linear, GitHub oder Ihrem Incident-Dokument:
## Claude model version not found incident
- Failing model string:
- API surface: Anthropic native / router / Bedrock / Vertex / other
- Base URL:
- Request path:
- SDK or client:
- Status code:
- error.type:
- request-id:
- First failing deploy:
- Current official model alias checked:
- Does minimal request pass?
- Is model enabled for this workspace/key/sub-key?
- Is this an unsupported feature error instead of model-not-found?
- Rollback model:
- Owner:
Halten Sie die Checkliste langweilig. Das Ziel ist zu verhindern, dass eine fehlende Claude-Model-Version zu einem weitreichenden Vorfall wird, bei dem jedes Team eine andere Einstellung ändert.
Häufig gestellte Fragen
Ist „Claude model version not found“ dasselbe wie ein 404?
Oft, aber nicht immer. Anthropic dokumentiert 404 - not_found_error für fehlende Ressourcen, während SDKs und Gateways die Meldung anders formulieren können. Bewahren Sie den rohen Statuscode und error.type auf, bevor Sie entscheiden.
Welche Claude-Model-Versionen sollte ich verwenden?
Verwenden Sie die aktuellen Modell-Aliase aus der API oder der Anbieteroberfläche, die Sie aufrufen. Kopieren Sie keine Claude-Model-Version von einem anderen Cloud-Anbieter, Router oder alten Codebeispiel, ohne den Katalog dieses Endpunkts zu prüfen.
Sollte ich einen Alias oder einen datierten Snapshot verwenden?
Für die meisten App-Teams ist ein aktueller Alias leichter zu betreiben, weil der Anbieter die unterstützte Zuordnung kontrolliert. Wenn Sie strikte Reproduzierbarkeit benötigen, dokumentieren Sie die genaue Snapshot-Richtlinie, den Ausmusterungsplan und den Rollback-Pfad.
Kann Flatkey Claude model version not found automatisch beheben?
Flatkey kann eine ungültige Upstream-Model-ID nicht gültig machen, aber es kann die Stellen reduzieren, an denen sich falsche IDs verstecken. Verwenden Sie Flatkey, um die Überprüfung des Modellkatalogs, One-Key-Routing, Sub-Key-Allowlists, Nutzungsprotokolle und Fallback-Richtlinien zu zentralisieren, wenn Claude nur ein Modellpfad unter vielen ist.
Wann sollte ich auf ein anderes Modell ausweichen?
Ein Fallback ist angemessen, nachdem Sie den Fehler klassifiziert haben. Weichen Sie nicht wegen eines Tippfehlers, einer falschen Basis-URL oder eines nicht autorisierten Schlüssels aus. Weichen Sie aus, wenn Ihre Richtlinie sagt, dass der aktuelle Pfad nicht verfügbar ist und der nächste Pfad dieselben Prüfungen für Eingabe, Qualität und Kosten bestanden hat.
Abschließende Prüfung
Bevor Sie ein claude model version not found-Ticket schließen, bestätigen Sie die Korrektur an drei Stellen: Quellkonfiguration, minimaler API-Smoke-Test und Produktions-Routenprotokolle. Fügen Sie dann die funktionierende Claude-Model-Version Ihrem Modellregister hinzu, damit die nächste Bereitstellung nicht dieselbe veraltete Zeichenfolge wieder einführt.
Wenn Sie bereits mehrere Modelle routen, testen Sie dieselbe Änderung über Flatkey, damit Ihr Request-Ledger, Ihre Fallback-Richtlinie und Ihre Modell-Allowlists vor dem Wechsel des Produktionsverkehrs alle übereinstimmen.
