API Timeout: Verbindungsabbrüche diagnostizieren und sichere Retries für LLMs einrichten

Wo Abbrüche entstehen: Die Phasen des HTTP-Anfragezyklus

Ein API-Aufruf an ein LLM durchläuft vier separate Phasen, die jeweils eigene Timeout-Einstellungen erfordern:

[Client] --- (1. Connect Timeout) ---> [API Gateway]
[Client] --- (2. Write Timeout)   ---> [Prompt-Übertragung]
[Modell] --- (3. Read / TTFT)     ---> [Reasoning & Antwort]
[Client] <--- (4. Pool Timeout)    --- [Socket-Haltung]

1. Connect Timeout: Zeitfenster für TCP-Handshake und TLS-Aushandlung (5–10 Sekunden empfohlen).
2. Write Timeout: Übertragung der Nutzlast (wichtig bei Prompt-Kontexten mit über 100k Tokens).
3. Read Timeout: Wartezeit auf die Antwort oder zwischen aufeinanderfolgenden SSE-Chunks.
4. Pool Timeout: Wartezeit auf einen freien Socket im Connection-Pool bei hoher Parallelität.

---

Diagnose-Matrix für Timeout-Fehler

---

Granulare Timeouts in Python (HTTPX) konfigurieren

Der Standardwert timeout=10.0 in gängigen Bibliotheken führt bei Reasoning-Modellen zwangsläufig zu Abbrüchen. Eine robuste Konfiguration sieht wie folgt aus:

import os
import httpx
from openai import OpenAI

API_KEY = os.environ.get("BETTERTOKEN_API_KEY", "your_api_key_here")

custom_timeout = httpx.Timeout(
    connect=5.0,    # Schneller Abbruch bei Nichterreichbarkeit
    read=120.0,     # Ausreichend Zeit für tiefe Reasoning-Schritte
    write=10.0,     # Sendezeit für große Prompts
    pool=10.0       # Wartezeit auf Pool-Sockets
)

http_client = httpx.Client(
    timeout=custom_timeout,
    limits=httpx.Limits(max_keepalive_connections=50, max_connections=100)
)

client = OpenAI(
    base_url="https://www.bettertoken.ai/v1",
    api_key=API_KEY,
    http_client=http_client
)

response = client.chat.completions.create(
    model="claude-3-7-sonnet-20250219",
    messages=[
        {"role": "system", "content": "You are a senior systems architect."},
        {"role": "user", "content": "Design a high-throughput distributed message broker."}
    ],
    stream=True
)

for chunk in response:
    delta = chunk.choices[0].delta.content or ""
    print(delta, end="", flush=True)
Mehr zeigen

---

SSE-Streams stabilisieren und sichere Wiederholungen einrichten

Um doppelte Kosten bei Verbindungsabbrüchen zu vermeiden, sollten Retries drei Kriterien erfüllen:

1. Kein Retry nach gestartetem Streaming: Wurden bereits Chunks empfangen, führt ein kompletter Neuversuch zu doppelter Token-Abrechnung.
2. Exponentieller Backoff mit Full Jitter: Wiederholungen müssen mit ansteigenden, randomisierten Pausen erfolgen.
3. Idempotenz-Schlüssel: Eindeutige Task-IDs bei Batch-Verarbeitung verhindern doppelte Ausführungen.

import time
import random
import httpx

def execute_with_safe_retry(client, model, messages, max_retries=3):
    base_delay = 1.0
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=messages,
                stream=True
            )
            return response
        except (httpx.ConnectTimeout, httpx.ReadTimeout, httpx.NetworkError) as err:
            if attempt == max_retries - 1:
                raise err
            sleep_time = random.uniform(0, base_delay * (2 ** attempt))
            time.sleep(sleep_time)

Abschlussprüfung

• HTTP-Status 200 OK.
• Fehlerfreier Empfang aller SSE-Chunks ohne Abbruch.
• Sofortige Freigabe genutzter Sockets nach Übertragungsende.

Weitere Integrationsbeispiele finden Sie in der BetterToken API Reference.