# 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
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

```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

```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

```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.

```python
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](https://tokenlane.de/docs/guides/errors-and-retries.md?lang=de), [Datenschutz und Compliance](https://tokenlane.de/docs/guides/privacy-and-compliance.md?lang=de) und im [Fehlerkatalog](https://tokenlane.de/docs/gateway/errors.md?lang=de).

SDK-Installation und Client-Einrichtung: [offizielle OpenAI-SDK-Dokumentation](https://developers.openai.com/api/docs/libraries). Das hier beschriebene Wiederholungs- und Abrechnungsverhalten ist der Vertrag des Tokenlane-Gateways.
