Claude API-Fehler

HTTP-Fehler

Die API folgt einem vorhersehbaren HTTP-Fehlercode-Format:

• 400 - invalid_request_error: Es gab ein Problem mit dem Format oder Inhalt deiner Anfrage. Dieser Fehlertyp kann auch für andere 4XX-Statuscodes verwendet werden, die in diesem Abschnitt nicht aufgeführt sind. Die API gibt außerdem einen 400 zurück, wenn die Nutzung ein von dir festgelegtes Ausgabenlimit für eine Organisation oder einen Workspace erreicht. Ausgenommen sind Limits für den Claude Code-Workspace, die stattdessen einen 429 zurückgeben können.

• 401 - authentication_error: Es gibt ein Problem mit deinem „API key“ (API-Key) (zum Beispiel ist er fehlerhaft formatiert, widerrufen oder abgelaufen; siehe Ablauf von Keys). Auf Claude Platform on AWS kann dies auch auf ein Problem mit deinen AWS-Anmeldedaten oder deiner SigV4-Signatur hinweisen.

• 402 - billing_error: Es gibt ein Problem mit deinen Abrechnungs- oder Zahlungsinformationen. Überprüfe deine Zahlungsdetails in der Claude Console oder im AWS Marketplace, wenn du Claude Platform on AWS verwendest.

• 403 - permission_error: Dein API-Key hat keine Berechtigung, die angegebene Ressource zu verwenden. Überprüfe die Zugriffs- und Workspace-Einstellungen deiner Organisation in der Claude Console.

• 404 - not_found_error: Die angeforderte Ressource wurde nicht gefunden. Überprüfe den Endpunktpfad und alle Ressourcen-IDs in der Anfrage-URL.

• 409 - conflict_error: Die Anfrage steht im Konflikt mit dem aktuellen Zustand einer Ressource. Zum Beispiel wurde die Ressource gleichzeitig geändert, oder ein Wert, der eindeutig sein muss, wird bereits verwendet. Löse den Konflikt und wiederhole dann die Anfrage.

• 413 - request_too_large: Die Anfrage überschreitet die maximal zulässige Anzahl an Bytes. Siehe Größenlimits für Anfragen für die Maximalwerte pro Endpunkt.

• 429 - rate_limit_error: Deine Organisation hat ein „rate limit“ (Ratenlimit) erreicht, die monatliche Ausgabenobergrenze ihrer Nutzungsstufe erreicht oder ein Ausgabenlimit für den Claude Code-Workspace erreicht. Ein 429 aufgrund der Ausgabenobergrenze einer Stufe hat keinen retry-after-Header und schlägt weiterhin fehl, bis der Zugriff wiederhergestellt ist; unter Erreichen deiner Ausgabenobergrenze erfährst du, wie du ihn erkennst.

• 500 - api_error: In den Systemen von Anthropic ist ein unerwarteter interner Fehler aufgetreten. Wiederhole die Anfrage mit „exponential backoff“ (exponentiellem Backoff); wenn der Fehler weiterhin besteht, kontaktiere den Support mit der Request-ID.

• 504 - timeout_error: Bei der Verarbeitung der Anfrage ist eine Zeitüberschreitung aufgetreten. Erwäge, für lang laufende Anfragen die Streaming Messages API zu verwenden. Weitere Optionen findest du unter Lange Anfragen.

• 529 - overloaded_error: Die API ist vorübergehend überlastet.

Die offiziellen SDKs wiederholen vorübergehende Fehler (wie Verbindungsfehler, Ratenlimits und 5xx-Serverfehler) automatisch mit exponentiellem Backoff, standardmäßig zweimal, und berücksichtigen dabei den retry-after-Header, sofern vorhanden. Der SDK-Client akzeptiert max_retries, um dieses Verhalten zu konfigurieren oder zu deaktivieren.

Beim Empfang einer Streaming-Antwort über „server-sent events“ (vom Server gesendete Ereignisse), oder SSE, kann ein Fehler auftreten, nachdem die API eine 200-Antwort zurückgegeben hat. In diesem Fall folgt die Fehlerbehandlung nicht diesen Standardmechanismen. Siehe Fehlerereignisse für die Form von Fehlern mitten im Stream.

Größenlimits für Anfragen

Die API erzwingt Größenlimits für Anfragen:

Wenn du diese Limits überschreitest, erhältst du einen 413-Fehler request_too_large. Bei der direkten Claude API gibt Cloudflare diesen Fehler zurück, bevor die Anfrage die API-Server erreicht.

Fehlerformen

Die API gibt Fehler immer als JSON zurück, mit einem error-Objekt auf oberster Ebene, das immer einen type- und einen message-Wert enthält. Die Antwort enthält außerdem ein request_id-Feld zur einfacheren Nachverfolgung und Fehlersuche. Zum Beispiel:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

In Übereinstimmung mit der Versionierungsrichtlinie können die Werte innerhalb dieser Objekte erweitert werden, und es ist möglich, dass die type-Werte im Laufe der Zeit zunehmen.

SDK-Fehlertypen

Die offiziellen SDKs lösen für diese Fehler typisierte Exceptions aus, anstatt rohes JSON zurückzugeben, und die Klassennamen und Namespaces unterscheiden sich je nach Sprache. Zum Beispiel erscheint ein 404 als anthropic.NotFoundError. Das Go SDK hat einen einzigen Fehlertyp für jeden Status, *anthropic.Error: Verzweige anhand von StatusCode. Fange die typisierten Klassen des SDK ab, anstatt Fehlermeldungen per String-Vergleich auszuwerten, und behandle dabei die spezifischsten Klassen zuerst. Jede SDK-Seite dokumentiert ihre vollständige Exception-Hierarchie:

• Python · TypeScript · C# · Go · Java · PHP · Ruby

Request-ID

Jede API-Antwort enthält einen eindeutigen request-id-Header. Dieser Header enthält einen Wert wie req_018EeWyXxfu5pfWkrYcMdjWG. Derselbe Bezeichner erscheint als request_id-Feld in den Fehlerantwort-Bodies. Wenn du den Support wegen einer bestimmten Anfrage kontaktierst, gib diese ID an, um dein Problem schnell lösen zu können.

Auf Claude Platform on AWS enthalten Antworten zwei Request-IDs: die AWS-Request-ID (x-amzn-requestid, primär, in CloudTrail indiziert) und die Anthropic-Request-ID (request-id, sekundär). Verwende die AWS-Request-ID für CloudTrail-Abfragen und die Anthropic-Request-ID für Anthropic-Support-Tickets.

Die Python- und TypeScript-SDKs stellen die Request-ID als _request_id-Eigenschaft auf Antwortobjekten der obersten Ebene bereit. Die C#-, Go-, Java- und PHP-SDKs stellen sie über ihre Zugriffsmethoden für Rohantworten bereit, und das Ruby SDK über Middleware. Verwende in jedem SDK außer Ruby with_raw_response, um jeden anderen Antwort-Header zu lesen, etwa anthropic-organization-id und anthropic-workspace-id. Verwende in Ruby dieselbe Middleware. Verwende auf Claude Platform on AWS die Zugriffsmethode für Rohantworten, um auch die AWS-Request-ID (x-amzn-requestid) zu lesen:

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")

Beispiele für Request-IDs auf Claude Platform on AWS in anderen Sprachen findest du unter Request-IDs.

Lange Anfragen

Vermeide es, einen großen max_tokens-Wert zu setzen, ohne die Streaming Messages API oder die Message Batches API zu verwenden:

• Einige Netzwerke können inaktive Verbindungen nach einer variablen Zeitspanne trennen, was dazu führen kann, dass die Anfrage fehlschlägt oder eine Zeitüberschreitung erfährt, ohne eine Antwort von Anthropic zu erhalten.
• Netzwerke unterscheiden sich in ihrer Zuverlässigkeit. Die Message Batches API kann dir helfen, das Risiko von Netzwerkproblemen zu steuern, indem sie dir ermöglicht, Ergebnisse abzufragen, anstatt eine ununterbrochene Netzwerkverbindung zu erfordern.

Wenn du eine direkte API-Integration erstellst, kann das Setzen eines TCP-Socket-Keep-Alive die Auswirkungen von Timeouts bei inaktiven Verbindungen in einigen Netzwerken verringern.

Die SDKs validieren, dass deine Nicht-Streaming-Anfragen an die Messages API voraussichtlich kein 10-Minuten-Timeout überschreiten. Sie setzen außerdem eine Socket-Option für TCP-Keep-Alive.

Wenn du Ereignisse nicht inkrementell verarbeiten musst, können die SDKs den Stream für dich konsumieren und das vollständige Message-Objekt zurückgeben, identisch mit dem, was ein Nicht-Streaming-Aufruf zurückgibt:

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-sonnet-5",
) as stream:
    message = stream.get_final_message()

print(next(block.text for block in message.content if block.type == "text"))

Siehe Streaming Messages für weitere Details.

Häufige Validierungsfehler

Prefill nicht unterstützt

Claude 4.6 und neuere Modelle sowie Claude Mythos Preview unterstützen das Vorbefüllen (Prefilling) von Assistant-Nachrichten nicht. Das Senden einer Anfrage mit einer vorbefüllten letzten Assistant-Nachricht an eines dieser Modelle gibt einen 400 invalid_request_error zurück:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "This model does not support assistant message prefill. The conversation must end with a user message."
  }
}

Verwende stattdessen strukturierte Ausgaben auf Modellen, die dies unterstützen, Anweisungen im „system prompt“ (System-Prompt) oder output_config.format.

Thinking-Blöcke können nicht geändert werden

Wenn die letzte Assistant-Nachricht thinking- oder redacted_thinking-Blöcke enthält, die bearbeitet, umsortiert, herausgefiltert oder rekonstruiert wurden, bevor sie an die API zurückgesendet wurden, gibt die Anfrage einen 400 invalid_request_error zurück. Die Fehlermeldung beginnt mit der Position des betreffenden Blocks (zum Beispiel messages.1.content.0) und enthält:

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response.

Bei „tool use“ (Tool-Nutzung) muss jeder thinking- und redacted_thinking-Block aus dem Assistant-Zug genau so zurückgegeben werden, wie er empfangen wurde, einschließlich Blöcken, deren thinking-Feld leer ist. Gib Thinking-Blöcke unverändert zurück, und wenn deine Anwendung Inhaltsblöcke vor dem erneuten Senden nach Typ filtert, schließe sowohl thinking als auch redacted_thinking ein. Siehe Fehlerbehebung beim Nachdenken, Thinking-Blöcke beibehalten und Beibehaltenes Nachdenken.

Erweitertes Nachdenken nicht unterstützt

Claude 4.7 und neuere Modelle haben „extended thinking“ (erweitertes Nachdenken) entfernt. Das Senden von thinking: {"type": "enabled"} an eines dieser Modelle gibt einen 400 invalid_request_error zurück:

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Verwende stattdessen adaptives Nachdenken. Migration zu adaptivem Nachdenken zeigt die Parameterzuordnung, und Fehlerbehebung beim Nachdenken behandelt die symptomorientierte Lösung.

Adaptives Nachdenken nicht unterstützt

Modelle, die nur erweitertes Nachdenken unterstützen (Claude 4.5 und ältere Modelle), lehnen thinking: {"type": "adaptive"} mit einem 400 invalid_request_error ab:

adaptive thinking is not supported on this model

Verwende auf diesen Modellen thinking: {"type": "enabled", "budget_tokens": N}; siehe Erweitertes Nachdenken für die Konfiguration und Fehlerbehebung beim Nachdenken für die symptomorientierte Lösung.

Nachdenken kann nicht deaktiviert werden

Bei Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5 und Claude Mythos Preview ist das Nachdenken immer aktiviert. Das Senden von thinking: {"type": "disabled"} an eines dieser Modelle gibt einen 400 invalid_request_error zurück. Bei allen diesen Modellen außer Claude Mythos Preview lautet die Meldung:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Bei Claude Mythos Preview, dem einzigen dieser Modelle, das erweitertes Nachdenken akzeptiert, lautet die Meldung:

"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.

Bei Claude Sonnet 5.5 kann das Nachdenken nicht auf disabled gesetzt werden. Verwende thinking: {"type": "between_tools"} für die niedrigste Nachdenk-Einstellung, die das vorgelagerte Nachdenken abschaltet. Das Senden von thinking: {"type": "disabled"} gibt einen 400-Fehler invalid_request_error mit dieser Nachricht zurück:

"thinking.type.disabled" is not supported for this model. Use "thinking.type.between_tools" for the lowest thinking setting, or "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Bei xhigh- oder max-Effort gibt eine Anfrage mit between_tools ebenfalls einen 400-Fehler invalid_request_error zurück. Die Nachricht besagt, dass das Nachdenken deaktiviert ist, weil between_tools kein vorgelagertes Nachdenken hat:

output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.

Mit between_tools kann sich der Effort nicht mitten in der Konversation ändern: Ein output_config.effort pro Nachricht, das von der aktuell geltenden Stufe abweicht, gibt einen 400-Fehler zurück. Der Fehler nennt die Position der Nachricht, die die neue Stufe festgelegt hat:

messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.

In beiden Nachrichten bedeutet „enable thinking" adaptives Nachdenken: Lass das thinking-Feld weg oder sende thinking: {"type": "adaptive"}. Claude Sonnet 5.5 lehnt "enabled" mit einem 400-Fehler ab. Um den Effort pro Turn zu variieren, verwende adaptives Nachdenken.

Das Senden von thinking: {"type": "between_tools"} an ein anderes Modell als Claude Sonnet 5.5 gibt einen 400-Fehler invalid_request_error zurück:

"thinking.type.between_tools" is not supported for this model.

Die Lösungen findest du unter Fehlerbehebung beim Nachdenken, wo die Fehler zu between_tools und Effort behandelt werden.

Lass den thinking-Parameter weg, dann wird die Anfrage mit adaptivem Nachdenken ausgeführt. Um Thinking-Inhalte aus Antworten herauszuhalten, ohne Thinking zu deaktivieren, setze display: "omitted" in der Thinking-Konfiguration. Siehe Fehlerbehebung beim Nachdenken.

Erzwungene Tool-Nutzung nicht unterstützt

Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 und Claude Mythos 5.1 unterstützen keine erzwungene Tool-Nutzung. Das Senden von tool_choice: {"type": "any"} oder tool_choice: {"type": "tool", "name": "..."} an eines dieser Modelle, auch am Token-Counting-Endpunkt, gibt einen 400-Fehler invalid_request_error zurück:

tool_choice: type "tool" and "any" are not supported for this model.

tool_choice: {"type": "auto"} (der Standard) und {"type": "none"} werden akzeptiert. Verwende auto mit strikter Tool-Nutzung, um Tool-Eingaben schemakonform zu halten, oder strukturierte Ausgaben, wenn du die Antwort selbst in einer festen JSON-Form benötigst. Siehe Tool-Nutzung erzwingen.

Version des Computer-Use-Tools nicht unterstützt

Auf der Claude API und Google Cloud unterstützen Claude Opus 5.5 und Claude Sonnet 5.5 Computer Use nur als Toolset computer_toolset_20260801. Auf diesen Plattformen gibt das Senden eines tools-Eintrags vom früheren Typ computer_20251124 (mit dem Beta-Header dieses Tools) an eines der beiden Modelle einen 400-Fehler invalid_request_error zurück. Die Nachricht nennt den abgelehnten Typ und listet dann nach Did you mean one of die Tool-Typen auf, die das Modell akzeptiert. Für Claude Opus 5.5 beginnt sie so:

'claude-opus-5-5' does not support tool types: computer_20251124.

Die API gibt dieselbe Nachricht für jeden von Anthropic definierten Tool-Typ zurück, den das angeforderte Modell nicht unterstützt. Deklariere {"type": "computer_toolset_20260801"} ohne den Beta-Header und aktualisiere deine Agent-Schleife wie unter Migration von computer_20251124 beschrieben. Frühere Modelle, die das Toolset unterstützen, akzeptieren weiterhin computer_20251124, ebenso wie Claude Opus 5.5 und Claude Sonnet 5.5 auf Amazon Bedrock.

Thinking-Block passt nicht mehr zur Konversation

Bei Claude Fable 5.1, Claude Opus 5.5 und Claude Sonnet 5.5 akzeptiert die API einen erneut gesendeten Thinking-Block nur, solange der system-Prompt, die tools und die vorangehenden Nachrichten unverändert sind. Bei neuen Konten, die am oder nach dem 31. August 2026 erstellt wurden, sowie bei jeder Anfrage, die thinking.block_binding.prefix_mismatch_behavior auf "error" setzt, wird ein erneut gesendeter Block, dessen vorheriger Verlauf sich geändert hat, mit einem 400-Fehler invalid_request_error abgelehnt (mit "drop_block" verwirft die API den Block und die Anfrage ist erfolgreich). Die Nachricht beginnt mit der Position des ersten fehlerhaften Blocks:

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

Ohne den Beta-Header thinking-binding-controls-2026-08-01 nennt die Nachricht auch diesen Header. Halte den Konversationsverlauf so, dass nur angehängt wird, oder sende den Beta-Header mit prefix_mismatch_behavior: "drop_block", um den Block zu verwerfen und fortzufahren. Bei Claude Sonnet 5.5 funktioniert block_binding nur mit thinking: {"type": "adaptive"}. Halte bei between_tools den Verlauf so, dass nur angehängt wird, oder entferne die Thinking-Blöcke ab dem bearbeiteten Turn. Ein Block von einem Modell, das das Zielmodell nicht lesen kann, wird verworfen statt abgelehnt. Siehe Das Präfix unverändert lassen und Fehlerbehebung beim Nachdenken.

Das Senden von thinking.block_binding ohne den Beta-Header thinking-binding-controls-2026-08-01 gibt einen 400 invalid_request_error zurück, dessen Meldung endet mit:

block_binding: Extra inputs are not permitted

Füge den Header hinzu oder entferne das Feld.

Outbound Web Identity Federation deaktiviert (Claude Platform on AWS)

Wenn jede Anfrage an Claude Platform on AWS "Outbound web identity federation is disabled for your account" zurückgibt, führe aws iam enable-outbound-web-identity-federation einmal pro AWS-Konto aus. Siehe Outbound Web Identity Federation aktivieren für Details.

Nächste Schritte