Idempotente Anfragen

Eine Anfrage kann fehlschlagen, nachdem Sursa die Arbeit bereits erledigt hat: Die Verbindung bricht ab, oder Ihr Prozess startet neu, bevor die Antwort ankommt. Senden Sie denselben POST erneut, könnten Sie eine zweite Karte oder einen zweiten Webhook anlegen. Ein Idempotenzschlüssel verhindert das.

Senden Sie bei jedem POST und PATCH einen Header Idempotency-Key. Hat Sursa bereits eine Anfrage mit diesem Schlüssel gesehen, führt es die Operation nicht erneut aus, sondern gibt die Antwort zurück, die es beim ersten Mal gespeichert hat.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

Eine wiederholte Anfrage erhält denselben Status und denselben Body wie die erste, mit einem zusätzlichen Header:

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

Die wiederholte Anfrage hat ihre eigene X-Request-Id.

Schlüssel wählen

Verwenden Sie für jede logische Operation einen neuen Zufallswert, etwa eine UUID v4: „diese Karte erstellen“, „diesen Webhook registrieren“. Verwenden Sie denselben Wert für jede Wiederholung dieser Operation und nie für eine andere.
Ein guter Schlüssel wird aus Ihren eigenen Daten abgeleitet, wenn Sie welche haben, zum Beispiel sync-2026-10-24-record-1042. Dann sendet selbst ein neu gestarteter Job, der seinen Zustand verloren hat, wieder denselben Schlüssel.
Der Schlüssel besteht aus 1 bis 255 druckbaren ASCII-Zeichen. Alles andere ergibt 400 mit dem Code api.idempotency_key_invalid.

Was Sursa mit dem Schlüssel macht

Situation	Antwort
Erste Anfrage mit diesem Schlüssel	Die Operation läuft wie gewohnt.
Gleicher Schlüssel, gleiche Anfrage, die erste endete mit `2xx` oder `4xx`	Die gespeicherte Antwort mit `Idempotency-Replayed: true`. Die Operation läuft nicht erneut.
Gleicher Schlüssel, die erste Anfrage läuft noch	`409` `api.idempotency_in_progress` mit `Retry-After: 1`. Warten Sie und versuchen Sie es erneut.
Gleicher Schlüssel, andere Methode, anderer Pfad, anderer `Content-Type` oder anderer Body	`409` `api.idempotency_mismatch`. Der Schlüssel ist bereits von einer anderen Anfrage belegt.
Die erste Anfrage endete mit `5xx` oder `429`	Der Schlüssel wird freigegeben: Die nächste Anfrage damit führt die Operation erneut aus.

Ein Schlüssel gilt 24 Stunden. Danach startet derselbe Schlüssel eine neue Operation.
Schlüssel sind pro Organisation und pro Aufrufer getrennt: Zwei verschiedene API-Schlüssel können denselben Wert verwenden, ohne sich gegenseitig zu beeinflussen.
Auch eine Fehlerantwort mit 4xx wird gespeichert. Eine Anfrage, die an der Validierung gescheitert ist, scheitert bei einer Wiederholung mit demselben Schlüssel genauso; korrigieren Sie sie und senden Sie sie mit einem neuen Schlüssel.

Welche Anfragen ihn brauchen

Methode	Idempotency-Key
`POST`, `PATCH`	Senden Sie ihn. Jeder Endpunkt, der seine Antwort für eine Wiederholung speichert, führt den Header in der API-Referenz auf.
`GET`, `PUT`, `DELETE`	Nicht nötig: Diese Methoden lassen sich ihrer Bedeutung nach gefahrlos wiederholen. Der Header wird akzeptiert und hat keine Wirkung.
`POST`, der nur liest, etwa die Suche, die Finanzberichte und `POST /v1/catalog/resolve`	Wird akzeptiert, aber nichts wird gespeichert: Die Anfrage läuft einfach erneut.

Einige Operationen lassen sich auch ohne den Header gefahrlos wiederholen:

PUT /v1/cards-by-external-id/{external_id} erstellt oder ersetzt die Karte mit Ihrer ID; eine Wiederholung mit demselben Inhalt ändert nichts.
Dokumente einer benutzerdefinierten Quelle werden über Ihre external_id zugeordnet; dasselbe Dokument erneut zu senden ergibt unchanged.
Eine gestreamte Antwort von POST /v1/chat verwendet statt des Headers das Feld request_id im Body. Siehe Q&A-Bot bauen.

Sicher wiederholen

Kombinieren Sie den Schlüssel mit den Wiederholungsregeln aus Fehler: Erzeugen Sie den Schlüssel einmal vor dem ersten Versuch und senden Sie ihn bei jedem Versuch derselben Operation mit.