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.

• 401 - authentication_error: Es gibt ein Problem mit deinem API-Key (zum Beispiel ist er fehlerhaft formatiert, widerrufen oder abgelaufen; siehe Key-Ablauf). Auf der 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 die Claude Platform auf 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 Endpunkt-Pfad 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: Dein Konto hat ein Ratenlimit erreicht.

• 500 - api_error: Ein unerwarteter Fehler ist intern in Anthropics Systemen aufgetreten. Wiederhole die Anfrage mit exponentiellem Backoff; wenn der Fehler weiterhin besteht, kontaktiere den Support mit der Request-ID.

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

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

  

  529-Fehler können auftreten, wenn die API hohen Traffic über alle Nutzer hinweg verzeichnet.

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

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, falls vorhanden. Jeder SDK-Client akzeptiert eine Option für die maximale Anzahl an Wiederholungen, um dieses Verhalten zu konfigurieren oder zu deaktivieren.

Beim Empfang einer Streaming-Antwort über Server-Sent Events (SSE) kann ein Fehler auftreten, nachdem die API eine 200-Antwort zurückgegeben hat. In diesem Fall folgt die Fehlerbehandlung nicht diesen Standardmechanismen. Siehe Fehler-Events für die Struktur 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 request_too_large-Fehler. Bei der direkten Claude API gibt Cloudflare diesen Fehler zurück, bevor die Anfrage die API-Server erreicht.



Fehlerstrukturen

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 Versionierungs-Richtlinie können sich die Werte innerhalb dieser Objekte erweitern, und es ist möglich, dass die type-Werte im Laufe der Zeit zunehmen.



SDK-Fehlertypen

Die offiziellen SDKs werfen für diese Fehler typisierte Exceptions, anstatt rohes JSON zurückzugeben, und die Klassennamen und Namespaces unterscheiden sich je nach Sprache. Zum Beispiel erscheint ein 404 als anthropic.NotFoundError in Python, Anthropic::Errors::NotFoundError in Ruby, com.anthropic.errors.NotFoundException in Java und als einzelner *anthropic.Error-Wert (Verzweigung über StatusCode) in Go. Fange die typisierten Klassen des SDKs ab, anstatt Fehlermeldungen per String-Vergleich zu prüfen, 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 Fehlerantwort-Bodies. Wenn du den Support zu einer bestimmten Anfrage kontaktierst, gib diese ID an, um dein Problem schnell zu lösen.

Auf der 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 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 Raw-Response-Accessoren bereit, mit denen du auch jeden anderen Antwort-Header lesen kannst. Auf der Claude Platform auf AWS kannst du den Raw-Response-Accessor auch verwenden, um 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}")

Für Request-ID-Beispiele der 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 das Zeitlimit überschreitet, 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 verwalten, indem sie dir ermöglicht, Ergebnisse abzufragen, anstatt eine ununterbrochene Netzwerkverbindung zu benötigen.

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

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

Wenn du Events 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(message.content[0].text)

Siehe Streaming Messages für weitere Details.



Häufige Validierungsfehler



Prefill 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, System-Prompt-Anweisungen oder output_config.format.



Thinking-Blöcke können nicht verändert 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 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-Nutzung muss jeder thinking- und redacted_thinking-Block aus dem Assistant-Turn 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 Content-Blöcke vor dem erneuten Senden nach Typ filtert, schließe sowohl thinking als auch redacted_thinking ein. Siehe Thinking-Blöcke bewahren und Thinking-Ausgabe bei Claude Fable 5 und Claude Mythos 5.



Outbound Web Identity Federation deaktiviert (Claude Platform auf AWS)

Wenn jede Anfrage an die 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.



Nächste Schritte