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.

• 401 - authentication_error: Es gibt ein Problem mit deinem API-Key. Bei Claude Platform auf 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 auf AWS verwendest.

• 403 - permission_error: Dein API-Key hat keine Berechtigung, die angegebene Ressource zu verwenden.

• 404 - not_found_error: Die angeforderte Ressource wurde nicht gefunden.

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

• 429 - rate_limit_error: Dein Konto hat ein Ratenlimit erreicht.

• 500 - api_error: Ein unerwarteter Fehler ist intern in den Systemen von Anthropic aufgetreten.

• 504 - timeout_error: Die Anfrage hat während der Verarbeitung das Zeitlimit überschritten. Erwäge die Verwendung von Streaming für lang laufende Anfragen.

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

  

  529-Fehler können auftreten, wenn APIs hohen Traffic über alle Nutzer hinweg verzeichnen.

  In seltenen Fällen, wenn deine Organisation einen starken Anstieg der Nutzung verzeichnet, könntest du 429-Fehler aufgrund von Beschleunigungslimits der API sehen. Um das Erreichen von Beschleunigungslimits zu vermeiden, steigere deinen Traffic schrittweise und halte konsistente Nutzungsmuster ein.

Beim Empfang einer Streaming-Antwort über SSE ist es möglich, dass ein Fehler auftritt, nachdem eine 200-Antwort zurückgegeben wurde. In diesem Fall würde die Fehlerbehandlung nicht diesen Standardmechanismen folgen.



Größenbeschränkungen für Anfragen

Die API erzwingt Größenbeschränkungen für Anfragen, um eine optimale Leistung zu gewährleisten:

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



Fehlerstrukturen

Fehler werden immer als JSON zurückgegeben, 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 für einfacheres Tracking und Debugging. 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. Ein 404 erscheint beispielsweise als anthropic.NotFoundError in Python, Anthropic::Errors::NotFoundError in Ruby, com.anthropic.errors.NotFoundException in Java und als einzelner *anthropic.Error-Wert (Verzweigung nach StatusCode) in Go. Fange die typisierten Klassen des SDKs ab, anstatt Fehlermeldungen per String-Matching zu vergleichen, 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. Wenn du den Support bezüglich einer bestimmten Anfrage kontaktierst, gib diese ID an, um dein Problem schnell zu lösen.

Bei Claude Platform auf 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 offiziellen SDKs stellen die Anthropic-Request-ID als Property auf Response-Objekten der obersten Ebene bereit, die den Wert des request-id-Headers enthält. Bei Claude Platform auf AWS verwende den Raw-Response-Accessor, um auch die AWS-Request-ID aus den HTTP-Headern auszulesen:

client = anthropic.Anthropic()

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

Für Request-ID-Beispiele zu Claude Platform auf AWS in anderen Sprachen siehe 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 ein Timeout 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 bewältigen, indem sie dir ermöglicht, Ergebnisse abzufragen, anstatt eine ununterbrochene Netzwerkverbindung zu erfordern.

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

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

Wenn du Events nicht inkrementell verarbeiten musst, verwende .stream() mit .get_final_message() (Python) oder .finalMessage() (TypeScript), um das vollständige Message-Objekt zu erhalten, ohne Event-Handling-Code schreiben zu müssen:

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

Siehe Streaming Messages für weitere Details.



Häufige Validierungsfehler



Prefill wird nicht unterstützt

Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 und Claude Sonnet 4.6 unterstützen kein Prefilling 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": "Prefilling assistant messages is not supported for this model."
  }
}

Verwende stattdessen strukturierte Ausgaben bei Modellen, die dies unterstützen, Anweisungen im System-Prompt oder output_config.format.



Thinking-Blöcke können nicht modifiziert werden

Wenn die letzte Assistant-Nachricht thinking- oder redacted_thinking-Blöcke enthält, die bearbeitet, neu angeordnet, 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 fehlerhaften 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-Nutzung muss jeder thinking- und redacted_thinking-Block aus dem Assistant-Turn exakt 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 Content-Blöcke vor dem erneuten Senden nach Typ filtert, schließe sowohl thinking als auch redacted_thinking ein. Siehe Thinking-Blöcke beibehalten und Thinking-Ausgabe bei Claude Fable 5 und Claude Mythos 5.



Outbound Web Identity Federation deaktiviert (Claude Platform auf AWS)

Wenn jede Anfrage an Claude Platform auf 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.