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

SituationErgebnisNächster Schritt
Erster RequestEine Provider-Ausführung mit normaler AntwortKey für mögliche Wiederholungen behalten
Derselbe abgeschlossene RequestIdentische Antwort mit Idempotent-Replayed: trueUrsprüngliche Generation-ID verwenden
Anderer Inhalt mit demselben Key409 idempotency_conflictNeuen Key für den geänderten Vorgang verwenden
Ursprünglicher Request läuft noch409 idempotency_in_progress mit Retry-AfterWarten und denselben Request erneut senden
Aufbewahrung abgelaufenEine neue kostenpflichtige Ausführung ist möglichAußerhalb der Frist nicht automatisch wiederholen
Antwort zu groß oder sichere Wiederholung unmöglichBei Wiederholung 409 idempotency_unavailableNicht automatisch mit neuem Key rechnen lassen
Replay-Verschlüsselung nicht eingerichtet501 feature_unavailable, retryable: false, kein Retry-AfterAbbrechen; Replay vor einem neuen Versuch vom Betreiber einrichten lassen
Wiederholbarer HTTP-5xx-Fehler oder bestätigter Client-AbbruchKein abgeschlossenes Ergebnis wird gespeichertMit demselben Key und begrenztem Backoff wiederholen; metadata.retryable: false niemals übergehen
HTTP 4xxDer Fehler wird gespeichert und wiederholtUrsache 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.