Claude API-Fehler

HTTP-Fehler

Die API folgt einem vorhersehbaren Format für HTTP-Fehlercodes:

• 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 einer Organisation oder eines Workspace erreicht, mit Ausnahme von 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, 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; siehe Erreichen deiner Ausgabenobergrenze, um zu erfahren, 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. Siehe Lange Anfragen für weitere Optionen.

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

Das offizielle SDK wiederholt vorübergehende Fehler (wie Verbindungsfehler, Ratenlimits und 5xx-Serverfehler) automatisch mit exponentiellem Backoff, standardmäßig zweimal, und berücksichtigt 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 Error-Events für die Struktur von Fehlern während des Streams.

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

Das offizielle SDK löst für diese Fehler typisierte Exceptions aus, anstatt rohes JSON zurückzugeben. 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 die spezifischsten Klassen zuerst. Die Seite deines SDK dokumentiert die 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 festzulegen, ohne die Streaming Messages API oder die Message Batches API zu verwenden:

• Manche Netzwerke trennen inaktive Verbindungen nach einer variablen Zeitspanne, was dazu führen kann, dass die Anfrage fehlschlägt oder eine Zeitüberschreitung auftritt, ohne dass eine Antwort von Anthropic empfangen wird.
• Netzwerke unterscheiden sich in ihrer Zuverlässigkeit. Die Message Batches API kann dir helfen, das Risiko von Netzwerkproblemen zu beherrschen, 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 Zeitüberschreitungen inaktiver Verbindungen in manchen Netzwerken verringern.

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

Wenn du Ereignisse nicht inkrementell verarbeiten musst, kann das SDK 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 von Nachrichten für weitere Details.

Häufige Validierungsfehler

Prefill nicht unterstützt

Claude 4.6 und neuere Modelle sowie Claude Mythos Preview unterstützen kein „prefilling" (Vorausfüllen) von Assistant-Nachrichten. Das Senden einer Anfrage mit einer vorausgefü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 bei Modellen, die diese unterstützen, Anweisungen im 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 Erhaltenes 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 Nachricht:

"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 Nachricht:

"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 deaktiviert. Das Senden von thinking: {"type": "disabled"} gibt einen 400 invalid_request_error mit dieser Nachricht zurück:

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

Bei xhigh- oder max-Effort gibt eine Anfrage mit between_tools ebenfalls einen 400 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 nachrichtenspezifisches output_config.effort, 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.

Claude Haiku 5.5 akzeptiert thinking: {"type": "disabled"} und unterwirft es denselben zwei Effort-Einschränkungen, die für between_tools gelten: Bei xhigh- oder max-Effort oder mit einem nachrichtenspezifischen output_config.effort, das von der aktuell geltenden Stufe abweicht, gibt die Anfrage einen 400 invalid_request_error mit der entsprechenden, weiter oben gezeigten Nachricht zurück.

In beiden Nachrichten bedeutet „enable thinking" adaptives Nachdenken: Lass das thinking-Feld weg oder sende thinking: {"type": "adaptive"}. Claude Sonnet 5.5 und Claude Haiku 5.5 lehnen "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 invalid_request_error zurück:

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

Für die Lösungen siehe Fehlerbehebung beim Nachdenken, wo die between_tools- und Effort-Fehler behandelt werden.

Lass den thinking-Parameter weg, und die Anfrage läuft mit adaptivem Nachdenken. Um Nachdenk-Inhalte aus Antworten herauszuhalten, ohne das Nachdenken zu deaktivieren, setze display: "omitted" in der Nachdenk-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 an den Token-Counting-Endpunkt, gibt einen 400 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-Struktur benötigst. Siehe Tool-Nutzung erzwingen.

Computer-Use-Tool-Version nicht unterstützt

Auf der Claude API und Google Cloud unterstützen Claude Opus 5.5, Claude Sonnet 5.5 und Claude Haiku 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 oder computer_20250124 mit dem Beta-Header dieses Tools an eines dieser Modelle einen 400 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. Für den Umstieg von computer_20250124 siehe Computer Use auf das Toolset umstellen im Migrationsleitfaden für Claude Haiku 5.5. Frühere Modelle, die das Toolset unterstützen, akzeptieren weiterhin computer_20251124, ebenso wie Claude Opus 5.5, Claude Sonnet 5.5 und Claude Haiku 5.5 auf Amazon Bedrock.

Thinking-Block passt nicht mehr zur Konversation

Bei Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 und Claude Haiku 5.5 akzeptiert die API einen erneut gesendeten Thinking-Block nur, solange der system-Prompt, die tools und die vorangegangenen Nachrichten unverändert sind. Für neue Konten, die am oder nach dem 31. August 2026 erstellt wurden, und für jede 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 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 append-only, oder sende den Beta-Header mit prefix_mismatch_behavior: "drop_block", um den Block zu verwerfen und fortzufahren. Bei Claude Sonnet 5.5 und Claude Haiku 5.5 funktioniert block_binding nur mit thinking: {"type": "adaptive"}. Mit between_tools bei Claude Sonnet 5.5 oder thinking: {"type": "disabled"} bei Claude Haiku 5.5 halte den Verlauf append-only, 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 Nachricht 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