Requests sicher wiederholen mit Idempotency
Mit einem festen Vorgangsschlüssel lässt sich nach einem Verbindungsfehler dieselbe fertige Antwort abrufen, ohne einen zweiten Provider-Aufruf oder eine zweite Abbuchung.
Einen Key je Vorgang wählen
Idempotency-Key bereits beim ersten Request und bei jeder Wiederholung mitsenden. Eine UUID einmal vor der Wiederholungsschleife erzeugen und bis zum Erfolg oder bewussten Abbruch des Vorgangs behalten. Ein neuer Vorgang benötigt einen neuen Key. Der Header darf genau einmal vorkommen und muss 1 bis 255 druckbare ASCII-Zeichen enthalten. Keine personenbezogenen Daten oder Geheimnisse als Wert verwenden.
Der Geltungsbereich ist die Identität des API-Keys. Ein anderer API-Key kann die Antwort nicht abrufen, auch kein zweiter Key derselben Organisation. Der Fingerabdruck berücksichtigt HTTP-Methode, Pfad und normalisierten Body. Reihenfolge der JSON-Objektschlüssel und Leerraum sind unerheblich. Geänderte Werte, eine andere Array-Reihenfolge oder ein anderer Endpunkt benötigen einen neuen Key. Bei Bodies außerhalb von JSON müssen die dekodierten Bytes und der Content-Type identisch bleiben.
Request senden
TOKENLANE_API_KEY auf den Gateway-Key setzen. Das SDK lässt sich mit npm install openai oder python -m pip install openai installieren. Die Beispiele verwenden ein aktuelles Modell aus dem Katalog. Für Wiederholungen über getrennte Prozesse denselben TOKENLANE_OPERATION_ID setzen. Die Variable vor einem neuen logischen Vorgang entfernen. Die Beispiele schalten automatische SDK-Wiederholungen aus, damit eine zusätzliche Schleife die Versuchszahl nicht vervielfacht.
curl
curl --fail-with-body --request POST \
--url 'https://api.tokenlane.de/v1/chat/completions' \
--header "Authorization: Bearer $TOKENLANE_API_KEY" \
--header "Idempotency-Key: ${TOKENLANE_OPERATION_ID:-$(python3 -c 'import uuid; print(uuid.uuid4())')}" \
--header 'Content-Type: application/json' \
--data '{"model":"deepseek/deepseek-v4-flash-0731","messages":[{"role":"user","content":"Hello"}],"max_tokens":400}'
node
import OpenAI from 'openai';
import { randomUUID } from 'node:crypto';
const client = new OpenAI({
baseURL: "https://api.tokenlane.de/v1",
apiKey: process.env.TOKENLANE_API_KEY,
maxRetries: 0,
});
const key = process.env.TOKENLANE_OPERATION_ID ?? randomUUID();
const body = {
"model": "deepseek/deepseek-v4-flash-0731",
"messages": [
{
"role": "user",
"content": "Hello"
}
],
"max_tokens": 400
};
const { data: completion, response } = await client.chat.completions
.create(body, { headers: { 'Idempotency-Key': key } })
.withResponse();
console.log({ generation: completion.id, replayed: response.headers.get('Idempotent-Replayed') === 'true' });
python
import json
import os
import uuid
from openai import OpenAI
client = OpenAI(
base_url="https://api.tokenlane.de/v1",
api_key=os.environ["TOKENLANE_API_KEY"],
max_retries=0,
)
key = os.environ.get("TOKENLANE_OPERATION_ID") or str(uuid.uuid4())
body = json.loads("{\"model\":\"deepseek/deepseek-v4-flash-0731\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"max_tokens\":400}")
response = client.chat.completions.with_raw_response.create(
**body, extra_headers={"Idempotency-Key": key}
)
completion = response.parse()
print({"generation": completion.id, "replayed": response.headers.get("Idempotent-Replayed") == "true"})
vercel
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';
import { randomUUID } from 'node:crypto';
const key = process.env.TOKENLANE_OPERATION_ID ?? randomUUID();
const tokenlane = createOpenAICompatible({
name: 'tokenlane', baseURL: "https://api.tokenlane.de/v1",
apiKey: process.env.TOKENLANE_API_KEY, includeUsage: true,
headers: { 'Idempotency-Key': key },
});
const result = await generateText({
model: tokenlane("deepseek/deepseek-v4-flash-0731"),
messages: [{ role: 'user', content: 'Hello' }],
providerOptions: { tokenlane: { max_tokens: 400 } },
maxRetries: 0,
});
console.log({ generated: result.text.length > 0 });
Eine Wiederholung erhält den ursprünglichen Status, Body, die Generation-ID, Request-ID und relevante Antwort-Header. Idempotent-Replayed: true kennzeichnet sie. Es entsteht keine neue Generation und keine zusätzliche Gebühr. Ohne Idempotency-Key gilt das gewöhnliche Inferenzverhalten; der Request aktiviert diesen Antwortspeicher nicht.
Ergebnis behandeln
| Situation | Ergebnis | Nächster Schritt |
|---|---|---|
| Erster Request | Eine Provider-Ausführung mit normaler Antwort | Key für mögliche Wiederholungen behalten |
| Derselbe abgeschlossene Request | Identische Antwort mit Idempotent-Replayed: true | Ursprüngliche Generation-ID verwenden |
| Anderer Inhalt mit demselben Key | 409 idempotency_conflict | Neuen Key für den geänderten Vorgang verwenden |
| Ursprünglicher Request läuft noch | 409 idempotency_in_progress mit Retry-After | Warten und denselben Request erneut senden |
| Aufbewahrung abgelaufen | Eine neue kostenpflichtige Ausführung ist möglich | Außerhalb der Frist nicht automatisch wiederholen |
| Antwort zu groß oder sichere Wiederholung unmöglich | Bei Wiederholung 409 idempotency_unavailable | Nicht automatisch mit neuem Key rechnen lassen |
| Replay-Verschlüsselung nicht eingerichtet | 501 feature_unavailable, retryable: false, kein Retry-After | Abbrechen; Replay vor einem neuen Versuch vom Betreiber einrichten lassen |
| Wiederholbarer HTTP-5xx-Fehler oder bestätigter Client-Abbruch | Kein abgeschlossenes Ergebnis wird gespeichert | Mit demselben Key und begrenztem Backoff wiederholen; metadata.retryable: false niemals übergehen |
| HTTP 4xx | Der Fehler wird gespeichert und wiederholt | Ursache korrigieren und neuen Vorgangsschlüssel verwenden |
Die Standardgrenze für Antworten beträgt 8 MiB. Eine zu große erste Antwort wird ausgeliefert, lässt sich aus diesem Speicher aber nicht wiederherstellen. Auch knapper lokaler Speicher oder ausgeschöpfte gemeinsame Kapazität können eine Wiederholung verhindern. remedy_hint beachten: Ein neuer Key startet bewusst einen neuen, möglicherweise kostenpflichtigen Vorgang. Ein gespeicherter 429 bleibt derselbe Fehler; Retry-After entfernt ihn nicht.
Anmeldung, ungültige Header und Transport-/Body-Grenzen werden vor einem nutzbaren Fingerabdruck geprüft und nicht als Wiederholungsdatensatz gespeichert. Bei einem Ausfall des gemeinsamen Zustands kann ein unvollständiger Vorgang bis zum Ablauf seiner Sicherheits-Lease als laufend gelten. Ein verlorener Cache erlaubt keine sofortige erneute Berechnung kostenpflichtiger Arbeit.
Wiederholungen mit Backoff begrenzen
Dieses Muster wiederholt Verbindungsfehler, vorübergehende Serverfehler und einen noch laufenden Vorgang. Ein ausdrückliches metadata.retryable: false beendet die Schleife auch bei HTTP 5xx, einschließlich 501 feature_unavailable. Andere 409- und 4xx-Antworten beenden die Schleife ebenfalls. Es behält einen Key, beachtet Retry-After, begrenzt die Versuchszahl und bricht ab, statt eine vom Server verlangte Pause über die Frist hinaus zu verkürzen. TOKENLANE_MODEL auf eine aktuelle Modell-ID aus dem Katalog setzen.
import os
import random
import time
import uuid
from openai import OpenAI, APIConnectionError, APIStatusError
client = OpenAI(
base_url=os.environ.get("TOKENLANE_BASE_URL", "https://api.tokenlane.de/v1"),
api_key=os.environ["TOKENLANE_API_KEY"],
max_retries=0,
)
key = str(uuid.uuid4())
body = {
"model": os.environ["TOKENLANE_MODEL"],
"messages": [{"role": "user", "content": "Hello"}],
"max_tokens": 400,
}
deadline = time.monotonic() + 45
for attempt in range(5):
remaining = deadline - time.monotonic()
if remaining <= 0:
raise TimeoutError("Retry deadline reached")
retry_after = 0.0
try:
result = client.chat.completions.create(
**body,
extra_headers={"Idempotency-Key": key},
timeout=min(15.0, remaining),
)
print(result.id)
break
except APIConnectionError:
if attempt == 4:
raise
except APIStatusError as error:
detail = error.body if isinstance(error.body, dict) else {}
detail = detail.get("error", detail)
detail = detail if isinstance(detail, dict) else {}
metadata = detail.get("metadata")
metadata = metadata if isinstance(metadata, dict) else {}
kind = metadata.get("type")
transient = metadata.get("retryable") is not False and (
error.status_code >= 500
or (error.status_code == 409 and kind == "idempotency_in_progress")
)
if not transient or attempt == 4:
raise
value = error.response.headers.get("Retry-After", "0")
if not value.isascii() or not value.isdecimal():
raise
retry_after = float(value)
delay = max(retry_after, min(8.0, 0.5 * 2**attempt) + random.uniform(0, 0.25))
if delay >= deadline - time.monotonic():
raise TimeoutError("Retry-After exceeds retry deadline")
time.sleep(delay)
Stream vor der Wiederholung abschließen
Das erste Stream-Byte wird sofort weitergeleitet. Erst ein vollständig erfolgreich abgeschlossener Stream kann einschließlich Usage-Ereignissen und [DONE] wiederholt werden. Ein unterbrochener oder fehlgeschlagener Stream ist kein abgeschlossenes Ergebnis. Die Wiederholung beginnt am Anfang und setzt nicht nach dem letzten empfangenen Token fort. Teiltext verwerfen, bevor er durch eine wiederhergestellte vollständige Antwort ersetzt wird. Einen neuen Stream nicht still an vorhandene Teilausgabe anhängen.
Speicherung und Datenschutz verstehen
Der Header ist ein ausdrückliches Opt-in für die Speicherung der vollständigen Antwort dieses Requests. Sie liegt verschlüsselt in Valkey und höchstens zehn Minuten ab Abschluss vor. Standard sind zehn Minuten; Betreiber können die Frist verkürzen. Idempotency schreibt sie nicht in den GenerationStore, erteilt keine capture-Berechtigung und macht sie nicht über GET /v1/generation/content abrufbar. Generation-Capture bleibt ein eigenes Opt-in. Prompts, Antworten, Authorization-Header und Werte des Idempotency-Headers gehören nicht in Logs oder Metriken.
Key und Request unverändert lassen und zeitnah wiederholen. Nach Ablauf kann derselbe Key einen weiteren kostenpflichtigen Vorgang auslösen. Weitere Hinweise stehen unter Fehler und Wiederholung, Datenschutz und Compliance und im Fehlerkatalog.
SDK-Installation und Client-Einrichtung: offizielle OpenAI-SDK-Dokumentation. Das hier beschriebene Wiederholungs- und Abrechnungsverhalten ist der Vertrag des Tokenlane-Gateways.