Claude Platform Docs
API-ReferenzDie API verwenden

Claude API-Fehler

Verstehe die HTTP-Statuscodes, die Struktur von Fehlerantworten und die Request-IDs, die die Claude API zurückgibt, und behandle Fehler mit den typisierten Exceptions des SDK.

HTTP-Fehler

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

  • 400 - invalid_request_error: Es gibt ein Problem mit dem Format oder Inhalt deiner Anfrage. Die API verwendet diesen Fehlertyp möglicherweise auch für andere 4XX-Statuscodes, 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. Limits für den Claude Code-Workspace sind die Ausnahme: Sie können stattdessen einen 429 zurückgeben. Wenn die Meldung ein Problem mit deiner Anfrage nennt, suche es unter Häufige Validierungsfehler.

  • 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.

    Ein 401, dessen Meldung mit CORS requests are not allowed for this Organization beginnt, ist kein Problem mit deinem API-Key. Die Anfrage enthielt einen Origin-Header, den Browser hinzufügen, und deine Organisation kann die Claude API nicht direkt aus einem Browser aufrufen. Die Meldung wird mit because of custom retention settings oder because of its settings fortgesetzt. Die erste Variante erscheint nur bei Vereinbarungen zur Datenaufbewahrung wie „zero data retention“ (Null-Datenaufbewahrung), oder ZDR; die zweite ist der allgemeine Fall, der auch die Compliance API umfasst. Keine Änderung an der Browser-Anfrage behebt das Problem, sende die Anfrage daher von deinem eigenen Backend aus; siehe Browserbasierte Anwendungen.

  • 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. Ein starker Anstieg der Nutzung kann auch dann einen 429 verursachen, wenn du unter deinen Ratenlimits liegst; siehe „Ramp limits“ (Anstiegslimits).

  • 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. Wenn der Fehlertyp stattdessen timeout_error ist, siehe den Eintrag zu 504.

  • 504 - timeout_error: Bei der Verarbeitung der Anfrage ist eine Zeitüberschreitung aufgetreten. Die API gibt timeout_error auch mit anderen Statuscodes zurück, etwa einem 500, wenn eine Anfrage das Zeitlimit des Servers erreicht, bevor die Antwort beginnt. Verwende für lang laufende Anfragen an die Messages API die Streaming Messages API. 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 First-Party-Claude-API erzwingt diese Größenlimits für Anfragen. Für andere Plattformen siehe die API-Übersicht.

EndpunkttypMaximale Anfragegröße
Messages API128 MB
Token Counting API128 MB
Batch API256 MB
Files API500 MB

Wenn du diese Limits überschreitest, erhältst du einen 413-Fehler request_too_large. Bei der First-Party-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:

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

Gemäß der API-Versionierungsrichtlinie können die Werte innerhalb dieser Objekte erweitert werden, und es können neue type-Werte hinzukommen.

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:

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 APIVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. zu verwenden:

  • Manche Netzwerke können inaktive Verbindungen nach einer variablen Zeitspanne trennen, was dazu führen kann, dass die Anfrage fehlschlägt oder ein Timeout auftritt, ohne dass eine Antwort von Anthropic empfangen wird.
  • Netzwerke unterscheiden sich in ihrer Zuverlässigkeit. Die Message Batches APIVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. 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.

Das Anthropic SDK prüft, dass von deinen Nicht-Streaming-Anfragen an die Messages API nicht erwartet wird, dass sie ein 10-Minuten-Timeout überschreiten. Außerdem setzt es 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 Die endgültige Nachricht abrufen, ohne Ereignisse zu verarbeiten 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 Thinking-Blöcke in der Anfrage nicht mit dem übereinstimmen, was die API zurückgegeben hat, kann die Anfrage einen 400 invalid_request_error erhalten. 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 der Tool-Nutzung gibst du jeden thinking- und redacted_thinking-Block aus dem Assistant-Turn genau so zurück, wie er empfangen wurde, einschließlich Blöcken, deren thinking-Feld leer ist. Wenn deine Anwendung Inhaltsblöcke vor dem erneuten Senden nach Typ filtert, schließe sowohl thinking als auch redacted_thinking ein. Dieser Fehler unterscheidet sich von einer nicht bestandenen Präfixprüfung, deren Fehler besagt, dass ein Block an eine andere Konversation gebunden ist. Das Setzen der Einstellung prefix_mismatch_behavior behebt ihn möglicherweise nicht. Siehe die Lösung für geänderte Thinking-Blöcke unter Fehlerbehebung beim Nachdenken.

Erweitertes Nachdenken nicht unterstützt

Claude 4.7 und neuere Modelle unterstützen kein „extended thinking“ (erweitertes Nachdenken). 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. Die Parameterzuordnung findest du unter Migration zu adaptivem Nachdenken. Um den Fehler ausgehend von seinem Symptom zu beheben, siehe Ein 400-Fehler besagt, dass "thinking.type.enabled" nicht unterstützt wird.

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 bei diesen Modellen thinking: {"type": "enabled", "budget_tokens": N}; siehe Erweitertes Nachdenken für die Konfiguration und die symptomorientierte Lösung für den Fehler bei adaptivem Nachdenken unter Fehlerbehebung beim Nachdenken.

Nachdenken kann nicht deaktiviert werden

Bei Claude Fable 5.2, Claude Mythos 5.2, 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 Fehlermeldung 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 Meldungen 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" ebenfalls mit einem 400-Fehler ab. Um den Effort für jeden 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 die between_tools- und Effort-Fehler unter Fehlerbehebung beim Nachdenken.

Lass den thinking-Parameter weg, und die Anfrage läuft mit adaptivem Nachdenken. Um Nachdenk-Inhalte aus Antworten herauszuhalten, ohne das Nachdenken auszuschalten, setze display: "omitted" in der Nachdenk-Konfiguration. Siehe die Lösung für den Fehler bei deaktiviertem Nachdenken unter Fehlerbehebung beim Nachdenken.

Erzwungene Tool-Nutzung nicht unterstützt

Claude Fable 5.2, Claude Mythos 5.2, 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

Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 und Claude Haiku 5.5 geben einen 400-Fehler für jede Computer-Use-Tool-Version zurück, die sie nicht akzeptieren. Auf der Claude API gehört dazu computer_20251124 mit dem zugehörigen Beta-Header. computer_20250124 akzeptieren sie auf keiner Plattform. Die invalid_request_error-Nachricht der Claude API nennt den abgelehnten Typ und listet nach Did you mean one of die Tool-Typen auf, die das Modell akzeptiert. Für Claude Opus 5.5 beginnt die Nachricht so:

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

Die Claude API gibt dieselbe Nachricht für jeden von Anthropic definierten Tool-Typ zurück, den das angeforderte Modell nicht unterstützt. Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 und Claude Haiku 5.5 unterstützen Computer Use über das Toolset computer_toolset_20260801. Deklariere {"type": "computer_toolset_20260801"} ohne den Beta-Header und aktualisiere deine Agent-Schleife wie in Migration von computer_20251124 beschrieben. Um von computer_20250124 umzusteigen, siehe Computer Use auf das Toolset umstellen im Migrationsleitfaden für Claude Haiku 5.5.

Auf Amazon Bedrock akzeptieren Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 und Claude Haiku 5.5 außerdem das Tool computer_20251124 mit dem Beta-Header computer-use-2025-11-24. Sende computer-use-2025-11-24 bei der InvokeModel API von Amazon Bedrock im anthropic_beta-Array des Request-Bodys statt in einem Header. Informationen zu dieser API findest du unter Claude auf Amazon Bedrock (bedrock-runtime). Welche Modelle mit jeder früheren Version zu verwenden sind, findest du unter Frühere Tool-Versionen.

Thinking-Block an eine andere Konversation gebunden

Dieser 400-Fehler invalid_request_error bedeutet, dass bei einem Thinking-Block, den du zurückgesendet hast, die Präfixprüfung fehlgeschlagen ist. Vergleiche system, tools und die Nachrichten vor dem Block mit dem, was du gesendet hast, als das Modell ihn erzeugt hat. Welche Änderungen relevant sind, findest du unter Was als Änderung zählt. Die Fehlermeldung beginnt mit der Position des ersten Blocks, bei dem die Präfixprüfung fehlschlägt:

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".

Das erneute Senden desselben Verlaufs schlägt auf die gleiche Weise fehl. Den Code zu korrigieren, der die Änderung vorgenommen hat, hilft dieser Konversation nicht, wenn die Änderung noch in ihrem Verlauf steht. Um fortzufahren, tu eines der Folgenden:

  • Sende den Beta-Header thinking-binding-controls-2026-08-01 und setze thinking.block_binding.prefix_mismatch_behavior auf "drop_block", beim erneuten Versuch und bei jeder späteren Anfrage in dieser Konversation. Bei Claude Sonnet 5.5 und Claude Haiku 5.5 funktioniert block_binding nur mit thinking: {"type": "adaptive"}.
  • Entferne den im Fehler genannten Block und jeden thinking- und redacted_thinking-Block danach, in dieser Nachricht und in jeder späteren Nachricht. Versuche es erneut und lass die entfernten Blöcke in späteren Anfragen weg.

Damit neue Konversationen nicht fehlschlagen, halte den Verlauf append-only (nur anhängend). Siehe die Lösung für eine ungültige Thinking-Block-Signatur unter 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, schalte das Nachdenken ein 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 für jedes AWS-Konto aus. Siehe Ausgehende Web-Identity-Federation aktivieren für Details.

Nächste Schritte

Symptomorientierte Lösungen für 400-Fehler bei der Thinking-Konfiguration, leere Thinking-Blöcke und max_tokens-Stopps.

Um Missbrauch einzudämmen und die Kapazität der API zu verwalten, gibt es Limits dafür, wie viel eine Organisation die Claude API nutzen kann.

Streame Antworten der Messages API inkrementell mit Server-Sent Events, einschließlich Deltas für Text, Tool-Nutzung und erweitertes Nachdenken.

War diese Seite hilfreich?