API Timeout: Verbindungsabbrüche diagnostizieren und sichere Retries entscheiden
Praxisleitfaden zum Lokalisieren von LLM-API-Timeouts, gezielten Ändern des verantwortlichen Limits und sicheren Prüfen der Wiederherstellung.
Inhalt
API Timeout: Verbindungsabbrüche diagnostizieren und sichere Retries entscheiden
Ein API Timeout bedeutet, dass ein Teilnehmer in der Anfragekette nicht länger gewartet hat. Der Client konnte die Verbindung nicht herstellen, ein Proxy schloss einen inaktiven Stream, die Gesamtfrist der Anwendung lief ab oder ein Gateway erhielt nicht rechtzeitig eine Upstream-Antwort. Die Meldung allein beweist keinen Modellausfall.
Erfassen Sie vor einem Retry Ausnahmeklasse, HTTP-Status und Body, verstrichene Zeit, Request-ID und bereits empfangene Chunks. Ändern Sie danach nur das Limit der bestätigten Schicht. Pauschal längere Timeouts verdecken die Ursache und können eine Operation mit unbekanntem Ergebnis wiederholen.
Wenn der Request BetterToken verwendete, öffnen Sie vor dem Retry das Dashboard und gleichen Sie Zeit, Modell, Status und Token-Nutzung ab. So trennen Sie einen Request, der die API erreichte, sofort von einem Fehler vor dem Gateway.
Warum ein Timeout nicht nur eine Ursache hat
Anwendung / SDK
→ DNS und TCP/TLS
→ Unternehmens- oder Reverse-Proxy
→ API-Gateway
→ Upstream-Modell
→ Streaming-Antwort zum ClientEin Connect Timeout betrifft DNS, TCP oder TLS. Ein Read- oder Stream-Idle-Timeout bedeutet, dass innerhalb des Client-Limits kein nächster Antwort-Chunk kam. Ein Pool Timeout entsteht beim Warten auf eine freie Client-Verbindung. Die Gesamt-Deadline begrenzt die vollständige Geschäftsoperation, während ein Upstream Timeout ein separates Limit des Gateways oder Providers ist. Das Verlängern eines Timers verlängert die anderen nicht.
Die Abbruchschicht bestimmen
| Signal | Wahrscheinliche Schicht | Nächste Prüfung |
|---|---|---|
httpx.ConnectTimeout, keine HTTP-Antwort | DNS, TCP oder TLS | Aus derselben Laufzeit testen; DNS, CA, Proxy und Firewall vergleichen |
httpx.ReadTimeout vor oder zwischen Chunks | Client Read/Idle oder Zwischen-Proxy | Zeit bis zum ersten Byte und zwischen Chunks messen; Proxy-Idle-Limits prüfen |
| HTTP-Status und Fehlerbody vorhanden | Gateway oder Upstream | Status, Body und Request-ID speichern; den Fehlervertrag des Providers anwenden |
httpx.PoolTimeout | Client-Pool | Nebenläufigkeit und Poolbelegung messen; Limits nur bei bestätigter Sättigung ändern |
| Abbruch stets nach derselben Gesamtdauer | Anwendung, Job Runner oder Reverse Proxy | Eigentümer der Deadline finden und mit allen unteren Timern vergleichen |
Gehen Sie in dieser Reihenfolge vor: zuerst Signal sichern, dann aus demselben Container oder Host reproduzieren, anschließend jeden Zwischen-Proxy prüfen und erst danach Gateway oder Upstream bewerten. Halten Sie Modell, Prompt, Netzwerk, Endpoint und Proxy konstant und ändern Sie pro Test nur eine Variable.
HTTPX dokumentiert getrennte Connect-, Read-, Write- und Pool-Timeouts. Konkrete Werte sind keine universellen Empfehlungen: Sie müssen aus gemessenen Phasen, erwarteten Pausen zwischen Chunks und der Gesamt-Deadline abgeleitet werden.
Wann Timeout, Ausgabe oder Retry geändert werden
- Ändern Sie den Connect Timeout nur bei nachgewiesen langsamem DNS/TCP/TLS-Aufbau.
- Ändern Sie den Read- oder Idle-Timeout, wenn die Verbindung steht, aber zwischen Chunks ein bestätigtes Zwischenlimit abläuft.
- Ändern Sie die Gesamt-Deadline nur, wenn die Geschäftsoperation länger dauern darf und alle unteren Schichten korrekt arbeiten.
- Reduzieren oder teilen Sie die Ausgabe, wenn nur der kontrollierte lange Test scheitert; verwenden Sie das nicht ohne Messung als pauschale Erklärung.
- Behandeln Sie
429und Kontextüberlauf getrennt. Ein solcher Status ist kein Connect Timeout.
Sicherer Retry ohne unbekannte Operation zu duplizieren
Nach dem Senden ist ein Timeout zunächst ein unbekanntes Ergebnis. Ein lokaler Task-ID hilft bei der Log-Zuordnung, verhindert aber keine zweite Serveroperation. Wiederholen Sie automatisch nur, wenn der Server dokumentierte Idempotenz oder eine Statusabfrage bietet und externe Evidenz zeigt, dass der erste Request nicht angenommen wurde.
Minimaler Check:
- Request-ID, Status/Body, Zeitstempel und empfangene Chunks sichern.
- Bei einer nicht idempotenten Aktion zuerst das tatsächliche Ergebnis prüfen.
- Einen teilweise empfangenen Stream nicht automatisch neu senden; das kann eine zweite Generierung und zusätzliche Nutzung erzeugen.
- Sowohl Versuchsanzahl als auch Gesamt-Deadline begrenzen und Retries von SDK, Proxy und Anwendung zusammenzählen.
- Auch Fehler erfassen, die während der SSE-Iteration auftreten, nicht nur beim Erstellen des Response-Objekts.
Zwei Tests bestätigen die Behebung
- Kurze Kontrollanfrage: Kleine Antwort anfordern; HTTP-Status, Zeit bis zum ersten Byte, Gesamtdauer, Request-ID und Stream-Ende notieren. Scheitert sie, zuerst Verbindung, Authentifizierung und Endpoint prüfen.
- Kontrollierte lange Anfrage: Nach erfolgreichem Kurztest nur die erwartete Ausgabe erhöhen oder die ursprüngliche Last wiederherstellen. Modell, Endpoint, Netzwerk und Proxy unverändert lassen. Scheitert nur dieser Test, Read/Idle-Timer, Gesamt-Deadline und Zwischenlimits vergleichen.
Die Behebung ist bestätigt, wenn der Kurztest und eine Wiederholung des ursprünglichen Szenarios mit erwartbarem Ergebnis und ohne unerklärtes Duplikat enden. Wenn der Request BetterToken erreicht hat, gleichen Sie im Dashboard Zeit, Modell, Status und Token-Nutzung ab und prüfen Sie anschließend den Endpoint-Vertrag.
