Claude-API-Anfrage-Timeouts und „Streaming wird dringend empfohlen“

Zwischen Ihnen und dem Modell gibt es normalerweise drei Timeouts — das Ihres SDKs, das eines Vermittlers und die eigene Regel des Providers für lange nicht gestreamte Aufrufe — und das kürzeste gewinnt. Nur das SDK-Timeout zu erhöhen erklärt, warum dies weiterhin passiert, obwohl Sie dachten, das Problem behoben zu haben.

Der Fehler

two shapes

# Rejected before generating, for a long non-streaming request:
{"type":"error","error":{"type":"invalid_request_error",
 "message":"Streaming is strongly recommended for operations that may take
 longer than 10 minutes."}}

# Or the client-side companion, with no response at all:
APITimeoutError: Request timed out.

Ursachen und Lösungen im Überblick

Ursache	Lösung
Eine lange nicht gestreamte Generierung	Streamen Sie sie. Lange Vervollständigungen sollten gestreamt werden, statt darauf zu warten.
SDK-Client-Timeout kürzer als die Generierungsdauer	Erhöhe ihn – aber erhöhe auch das Limit des Vermittlers, sonst ändert sich nichts.
Ein Proxy, Load Balancer oder eine serverlose Funktion, die die Anfrage begrenzt	Finde das kürzeste Limit in der Kette; genau dieses erreichst du.
Verbindung akzeptiert, dann keine Antwort	Ein Hänger, keine langsame Antwort. Begrenze die Zeit bis zum ersten Byte separat.

Alles streamen, was länger als ein paar Minuten dauern könnte

Streaming verhindert nicht nur das Erreichen des Limits, sondern liefert auch ein Lebenszeichen: Wenn Tokens eintreffen, arbeitet das Modell. So lässt sich ein Hänger von langsamem Fortschritt unterscheiden. Bei einem einzigen blockierenden Aufruf sehen beide Fälle bis zum Auslösen des Timeouts identisch aus.

Erhöhe jedes Timeout in der Kette, nicht nur das des SDKs

Fast immer ändern Leute den Client und belassen es dabei. Wenn ein Reverse-Proxy oder eine serverlose Plattform die Anfrage unter deinem neuen Client-Timeout begrenzt, gewinnt weiterhin dieses Limit und das Symptom ändert sich nicht.

client.py

from anthropic import Anthropic

# Client timeout is only one of the limits in play.
client = Anthropic(api_key=KEY, timeout=600.0)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8192,
    messages=[{"role": "user", "content": prompt}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Begrenze die Zeit bis zum ersten Byte getrennt von der Gesamtdauer

Das sind zwei verschiedene Fehler, die zwei verschiedene Maßnahmen erfordern. Eine kurze Frist für das erste Byte erkennt eine tote Verbindung schnell; eine großzügige Gesamtfrist lässt eine tatsächlich lange Generierung abschließen. Ein gemeinsames Timeout kann beides nicht leisten.

Sorge für sichere Wiederholungen, bevor du sie hinzufügst

Eine Anfrage, bei der dein Timeout ausgelöst wurde, kann upstream bereits abgeschlossen sein. Wenn die Arbeit Nebenwirkungen hat oder du pro Aufruf abgerechnet wirst, füge auf deiner Ebene Idempotenz hinzu, bevor du eine Wiederholungsschleife einbaust.

Wenn Sie Kunavo verwenden

Kunavo veröffentlicht eigene Zahlen, statt dich sie erst entdecken zu lassen: Kunavo wartet höchstens 240 Sekunden auf die Response-Header des Upstreams, und eine Antwort ohne Streaming sendet ihre Header normalerweise erst, wenn sie vollständig ist. Daher wird ein nicht gestreamter Aufruf, der länger als diese Zeit benötigt, über das Gateway nicht abgeschlossen – streame ihn. Die Begrenzung auf 240 Sekunden gilt nur für die Zeit bis zu den Headern und wird in dem Moment aufgehoben, in dem die Header eintreffen; ein langer Stream wird dadurch nie abgeschnitten. Nichts anderes im Gateway begrenzt die Länge eines Streams. Was einen Stream beendet, ist Stille: 300 Sekunden ohne ein Byte vom Upstream oder 600 Sekunden ohne ein Byte auf der Verbindung zu dir. Die synchronen Bild-, Video- und Musik-Routen halten die Verbindung bis zu 540 Sekunden offen, während ein Rendering abgeschlossen wird, innerhalb dieses 600-Sekunden-Fensters, weil Renderings legitimerweise mehrere Minuten dauern. Eine Anfrage, bei der das Timeout vor den Headern ausgelöst wird, zählt als Kanalausfall, wird auf dem nächsten konfigurierten Kanal des Modells wiederholt und mit Kosten von null erfasst.

Häufig gestellte Fragen

Wird eine Anfrage, bei der das Timeout ausgelöst wurde, berechnet?

Bei Kunavo nein – fehlgeschlagene Anfragen werden mit Kosten von null erfasst. Bei direkter Abrechnung durch einen Anbieter hängt es davon ab, ob die Generierung tatsächlich stattgefunden hat.

Warum vermeidet Streaming das Limit?

Die Antwort beginnt innerhalb weniger Sekunden und die Verbindung bleibt aktiv, sodass kein einzelner Zeitraum der Stille lang genug ist, um ein Timeout auszulösen.

Wie sollte mein Client-Timeout aussehen?

Länger als deine längste realistische Generierung, kombiniert mit einer kurzen separaten Frist für das erste Byte. Ein langes gemeinsames Timeout verwandelt jeden Hänger in einen mehrminütigen Stillstand.

Claude-API-Anfrage-Timeouts und „Streaming wird dringend empfohlen“ — die 10-Minuten-Regel