FlowModels

Anfragen sicher wiederholen: Idempotency-Key, Retry-After und Rate-Limit-Header

Veröffentlicht am 11. November 2026

Netzwerke sind nicht perfekt. Läuft eine Anfrage in einen Timeout, weißt du nicht, ob sie bei uns angekommen ist und schon Kosten verursacht hat. Mit einem Idempotency-Key kannst du sie gefahrlos wiederholen. Dazu kommen Header, die dir sagen, wie viele Anfragen du noch senden darfst und wie lange du warten sollst. Hier steht, wie du beides für eine robuste Wiederholungslogik nutzt.

Was ein Idempotency-Key bewirkt

Du schickst bei einer schreibenden Anfrage (POST, PUT, PATCH, DELETE) den Header Idempotency-Key mit einem Wert, den du für diesen einen Vorgang erzeugst. Schickst du später genau dieselbe Anfrage mit demselben Schlüssel noch einmal, führen wir sie nicht erneut aus. Ist die erste Anfrage erfolgreich abgeschlossen, bekommst du ihre gespeicherte Antwort zurück, ohne neue Kosten.

curl https://api.flowmodels.one/v1/chat/completions \
  -H "Authorization: Bearer at_dein_schluessel" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: bestellung-58213-zusammenfassung" \
  -d '{"model": "groq/openai/gpt-oss-120b", "messages": [{"role": "user", "content": "Fasse die Bestellung 58213 zusammen."}]}'

Der Schlüssel ist 1 bis 128 Zeichen lang und besteht aus Buchstaben, Ziffern, Punkt, Unterstrich und Bindestrich. Eine UUID passt immer. Die gespeicherte Antwort halten wir standardmäßig 24 Stunden bereit.

Bei einer wiederholten Antwort steht im Header Idempotent-Replay: true. Im Inhalt steht die flowai_request_id der ersten Anfrage, im Header x-request-id die Kennung der aktuellen Wiederholung.

Die drei Regeln für den Schlüssel

  1. Ein Schlüssel je Vorgang, nicht je Versuch. Erzeuge den Schlüssel, bevor du das erste Mal sendest, und verwende ihn für alle Wiederholungen dieses Vorgangs.
  2. Nach einem Abbruch nicht auf einen neuen Schlüssel wechseln. Die erste Anfrage kann schon verarbeitet und berechnet worden sein. Ein neuer Schlüssel würde sie ein zweites Mal ausführen.
  3. Geänderte Anfrage, neuer Schlüssel. Schickst du mit demselben Schlüssel einen anderen Inhalt oder einen anderen Dateinamen, antwortet die API mit 422 idempotency_key_reuse.

Läuft die erste Anfrage noch, oder ist ihr Ergebnis nach einer Störung nicht sicher bekannt, kommt sofort 409 idempotency_key_in_progress. Warte dann kurz und wiederhole mit demselben Schlüssel.

Ein Idempotency-Key funktioniert nur bei JSON- und Multipart-Anfragen. Mit einem anderen Content-Type gibt es 415 invalid_content_type.

Rate-Limit-Header lesen

Jede Antwort, die gegen dein Anfragelimit gezählt wurde, trägt diese Header:

  • x-ratelimit-limit-requests: wie viele Anfragen je Minute du senden darfst
  • x-ratelimit-remaining-requests: wie viele davon noch übrig sind
  • x-ratelimit-reset-requests: wann das Kontingent wieder voll ist, zum Beispiel 0s oder 1m30s

Bei Ablehnungen wegen Guthaben, Ausgabenlimit oder zu vielen gleichzeitigen Anfragen fehlen diese Header, weil dort nicht das Minutenlimit der Grund ist. Wie die Stufen funktionieren, erklärt Anfragelimit: So funktionieren die Stufen.

Was du automatisch wiederholen darfst

Antwort Automatisch wiederholen?
429 rate_limit_exceeded ja, nach der Wartezeit aus Retry-After
429 concurrent_requests_exceeded ja, nach Retry-After, und weniger parallel senden
502, 503 provider_overloaded, 503 routing_unavailable ja, nach Retry-After oder mit wachsender Wartezeit
409 idempotency_key_in_progress ja, kurz warten, gleicher Schlüssel
429 insufficient_quota, 429 spend_limit_exceeded nein, erst Guthaben oder Limit ändern
400, 401, 403, 404, 422 nein, erst die Anfrage korrigieren

Abgelehnte Anfragen mit 429 kosten nichts und hinterlassen keinen gespeicherten Idempotenzeintrag.

Ein Beispiel in Python

import time, uuid, requests

URL = "https://api.flowmodels.one/v1/chat/completions"
WIEDERHOLBAR = {"rate_limit_exceeded", "concurrent_requests_exceeded", "idempotency_key_in_progress"}

def fehlercode(antwort):
    try:
        return (antwort.json().get("error") or {}).get("code")
    except ValueError:
        return None

def frage_senden(payload):
    schluessel = str(uuid.uuid4())  # einmal je Vorgang, für alle Versuche gleich
    for versuch in range(5):
        try:
            antwort = requests.post(
                URL,
                headers={"Authorization": "Bearer at_dein_schluessel", "Idempotency-Key": schluessel},
                json=payload,
                timeout=120,
            )
        except requests.exceptions.RequestException:
            time.sleep(2 ** versuch)  # Timeout: mit demselben Schlüssel erneut senden
            continue
        if antwort.status_code < 400:
            return antwort.json()
        if antwort.status_code in (502, 503) or fehlercode(antwort) in WIEDERHOLBAR:
            time.sleep(int(antwort.headers.get("Retry-After", 2 ** versuch)))
            continue
        antwort.raise_for_status()  # alles andere nicht wiederholen
    raise RuntimeError("FlowModels nach 5 Versuchen nicht erreichbar")

Ein Timeout auf deiner Seite wird hier wie eine vorübergehende Störung behandelt: Die Anfrage geht mit demselben Schlüssel noch einmal raus. War die erste schon erfolgreich, bekommst du deren Antwort ohne neue Kosten.

Gut zu wissen

  • Jede Antwort trägt den Header x-request-id, auch Fehlerantworten. Schreib ihn in deine Logs. Damit findet der Support eine Anfrage sofort.
  • Ein abgebrochener Stream lässt sich nicht fortsetzen. Für lange Antworten ist ein Hintergrundauftrag robuster, siehe Lange Anfragen im Hintergrund.
  • Alle Fehlercodes erklärt Fehlermeldungen von FlowModels verstehen.

War dieser Artikel hilfreich?

Zurück zu Modelle, Limits & Fehler