Leitfaden

Idempotenz

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:

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:

{
  "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.

📮 contact email: [email protected]