Leitfaden

Idempotenz

Verändernde Anfragen lassen sich durch Senden eines Idempotency-Key gefahrlos wiederholbar machen. Geht eine Anfrage durch ein Timeout verloren, liefert ihre Wiederholung mit demselben Schlüssel das ursprüngliche Ergebnis zurück, statt ein Duplikat zu erzeugen.

Der Idempotency-Key-Header

Schicke bei jedem POST, PUT oder PATCH einen eindeutigen Schlüssel mit (eine UUID ist ideal). Der Server speichert das Ergebnis 24 Stunden unter diesem Schlüssel und gibt es bei jeder Wiederholung mit demselben Schlüssel erneut aus.

Die Regeln

Erzeuge pro logischer Operation einen frischen Schlüssel, noch vor dem ersten Versuch.
Verwende für Wiederholungen genau dieser Operation denselben Schlüssel.
Die Wiederverwendung eines Schlüssels mit einem anderen Body liefert IDEMPOTENCY_KEY_REUSED, niemals stille Datenbeschädigung.
GET-Anfragen ignorieren den Header. Die meisten DELETE-Routen akzeptieren ihn ebenfalls, wiederholte Löschungen bleiben also sicher.

Beispiel

Eine Transaktion mit einem Schlüssel erstellen: Die Wiederholung des Aufrufs liefert dieselbe Transaktion zurück, keine zweite.

bash

curl -H "Authorization: Bearer vokse_sk_…" \     -H "Content-Type: application/json" \     -H "Idempotency-Key: 7c2f9b1e-4a8d-4e3a-9c1b-2f6e8d0a1b3c" \     -X POST https://api.vokse.ai/households/current/transactions \     -d '{"accountId":"01J8ME9AZ2K3W7X4V5T6R7Q8S9","date":"2026-06-22","amountCents":-4250,"currency":"EUR","payeeName":"Mercadona"}'