# Idempotenz — Sicheres Wiederholen mit dem Idempotency-Key-Header

> Verwenden Sie den Idempotency-Key-Header, um Dokument-Uploads, Batch-Verarbeitung und Bbox-Trigger sicher zu wiederholen, ohne dieselbe Operation zweimal auszuführen oder zu bezahlen.

Netzwerkaufrufe schlagen fehl und laufen aus. Wenn das bei einer Anfrage passiert, die Credits verbraucht oder eine Ressource erstellt, kann ein naives Wiederholen diese Credits doppelt verbrauchen. Der `Idempotency-Key`-Header löst das: Senden Sie denselben Schlüssel bei einer Wiederholung, und Sie erhalten exakt dieselbe Antwort wie beim ursprünglichen Aufruf – ohne dass die Operation erneut ausgeführt wird.

## So funktioniert es

Fügen Sie einen `Idempotency-Key`-Header mit einem beliebigen clientseitig generierten eindeutigen String (eine UUID ist eine gute Wahl) zu einer Anfrage hinzu, die dies unterstützt:

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3e9a2c-9b41-4e6a-8c3d-2f1a5b6c7d8e" \
  -d '{"fields": [{"name": "invoice_number"}, {"name": "total_amount"}]}'
```

Der Schlüssel wird pro `(Ihr Konto, Schlüsselwert, Endpunkt)` für **24 Stunden** gespeichert. Wenn innerhalb dieses Zeitfensters exakt dieselbe Anfrage (gleicher Endpunkt, gleicher Schlüssel) erneut eingeht, wird die ursprüngliche Antwort – gleicher Statuscode, gleicher Body – wiederholt, und die Operation selbst wird kein zweites Mal ausgeführt. Das bedeutet, dass ein `process`-Aufruf, der mit demselben Schlüssel wiederholt wird, keine Credits doppelt abzieht, und ein `documents`-Upload, der mit demselben Schlüssel wiederholt wird, kein zweites Dokument erstellt.

Anfragen ohne einen `Idempotency-Key`-Header verhalten sich genau wie zuvor – es wird nichts gespeichert, nichts wiederholt. Der Header ist vollständig optional.

## Welche Endpunkte unterstützen ihn

Nur Endpunkte, die Credits verbrauchen oder eine Ressource erstellen, akzeptieren `Idempotency-Key` — bei einem reinen Lese-`GET` bringt er keinen Vorteil, da eine wiederholte Leseoperation für sich genommen immer sicher ist:

- `POST /documents` (Dokumenterstellung)
- `POST /batches/{batch_name}/process` (startet die Verarbeitung, zieht Credits ab)
- `POST /documents/{document_id}/bbox` (löst den kostenpflichtigen BBox-Annotationsschritt aus)

## Wiederverwendung eines Schlüssels mit anderen Parametern

Ein `Idempotency-Key` ist für die Wiederholung der *exakt gleichen* Anfrage gedacht, nicht als universelles Label. Wenn Sie einen bereits verwendeten Schlüssel erneut nutzen, diesmal jedoch mit anderen Anfrageparametern — einem anderen `batch_name`, einem anderen Anfragekörper — gibt die API nicht stillschweigend die alte Antwort zurück (was bei einer anderen Anfrage falsch wäre) und rät nicht, welche Sie meinen. Stattdessen gibt sie einen 400-Fehler `idempotency_key_reused` zurück. Generieren Sie einen neuen Schlüssel, sobald die Anfrage tatsächlich anders ist, selbst wenn sie auf dieselbe Art von Operation abzielt.

## Beispiel: eine wiederholte Antwort

Der zweite Aufruf unten, der mit demselben Schlüssel wie ein bereits erfolgreicher Aufruf erfolgt, gibt denselben Körper und Statuscode wie der erste zurück — er zieht keine Credits erneut ab:

```json
{
  "batch_name": "260716-4K9P",
  "queued": 2,
  "quality": "fast",
  "webhook_registered": false
}
```

## Was aufgezeichnet wird

Nur erfolgreiche (2xx) Antworten werden für die Wiederholung gespeichert. Wenn der ursprüngliche Aufruf fehlschlug — ein Validierungsfehler, unzureichende Credits, irgendetwas nicht 2xx — wird nichts aufgezeichnet, und ein erneuter Versuch mit demselben Schlüssel führt die Operation einfach neu aus. Dies ist beabsichtigt: Ein Fehler ist genau die Situation, in der Ihr Wiederholungsversuch tatsächlich erneut versuchen soll, nicht denselben Fehler abgespielt zu bekommen, bis der Schlüssel 24 Stunden später abläuft.

---

Source: https://imagetotable.ai/de/developers/guides/idempotency