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
- 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.
- 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.
- 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 darfstx-ratelimit-remaining-requests: wie viele davon noch übrig sindx-ratelimit-reset-requests: wann das Kontingent wieder voll ist, zum Beispiel0soder1m30s
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.