Anfragen sicher wiederholen, ohne doppelte Verarbeitung

Wenn Sie eine Anfrage gesendet, aber keine Antwort erhalten haben, müssen Sie sie möglicherweise erneut senden. Mit einer Kennung für Wiederholungsversuche erkennt der Server, ob die Anfrage bereits verarbeitet wurde.

Bei erneuter Übermittlung mit derselben Kennung und demselben Inhalt erhalten Sie das ursprüngliche Ergebnis, ohne einen Gutschein doppelt auszustellen oder einen Stempel doppelt gutzuschreiben.

Verwendung

Erstellen Sie für jeden neuen Vorgang eine eindeutige Kennung und senden Sie sie im Header Idempotency-Key. Verwenden Sie dieselbe Kennung nur erneut, wenn Sie denselben Vorgang nach ausbleibender Antwort wiederholen.

Request
curl -X POST "https://api.vivoldi.com/api/coupon/v1/create" \
  -H "Authorization: APIKEY {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260920-000412" \
  -d '{
    "nm": "$5 discount coupon",
    "discTypeIdx": 458,
    "disc": 5
  }'

Wenn Sie den Header nicht senden können, verwenden Sie stattdessen das Feld requestId im Anfragekörper. Wenn Sie beides senden, müssen die Werte übereinstimmen.

Felder Beschreibung Typ
Idempotency-Key HTTP-Header. Verwenden Sie 8–64 Zeichen aus ASCII-Buchstaben, Ziffern und . _ : -. Nutzen Sie für jeden neuen Vorgang einen anderen Wert. string
requestId Feld im Anfragekörper. Es kann den Header ersetzen und hat dasselbe Format. string

Geltungsbereich

Dies gilt für das Erstellen und Einlösen von Gutscheinen sowie das Erstellen, Hinzufügen und Entfernen von Stempeln und das Einlösen von Prämien. Auch die v2-APIs zum Aktualisieren von Gutscheinen und Stempeln unterstützen diese Kennung.

Die Kennung ist optional. Ohne sie wird die Anfrage wie bisher verarbeitet. Einträge werden 72 Stunden gespeichert; danach kann eine Anfrage mit demselben Wert als neuer Vorgang gelten.

Kennungen werden nach Organisation und Vorgangsart getrennt. Verwenden Sie innerhalb einer Organisation denselben Wert nicht für unterschiedliche Vorgänge.

Antworten und Fehlerbehandlung

Wiederholen Sie eine bereits erfolgreiche Anfrage mit derselben Kennung und demselben Inhalt, erhalten Sie das ursprüngliche Ergebnis. Der Vorgang und der Webhook werden nicht erneut ausgeführt.

Bei Konflikten lautet der HTTP-Status 409 und code im Antworttext ebenfalls 409. Die Ursache steht in message. Prüfen Sie auch bei HTTP 200, ob code den Wert 0 hat.

Situation HTTP code Vorgehen
Erneuter Versuch mit derselben Kennung und demselben Inhalt 2000 Das ursprüngliche Ergebnis wird zurückgegeben. Weitere Schritte sind nicht nötig.
Dieselbe Kennung für anderen Inhalt verwendet 409409 Verwenden Sie für den neuen Vorgang eine neue Kennung.
Frühere Anfrage mit derselben Kennung wird noch verarbeitet 409409 Warten Sie kurz und wiederholen Sie die Anfrage mit derselben Kennung.
Header und requestId enthalten unterschiedliche Werte 4001213 Gleichen Sie die Werte an oder senden Sie nur einen davon.
Ungültiges Kennungsformat 4001216 Verwenden Sie 8–64 ASCII-Buchstaben, Ziffern oder diese Zeichen: . _ : -
Eine andere Anfrage hat dasselbe Objekt zuerst geändert 409409 Prüfen Sie den aktuellen Zustand und überarbeiten Sie dann Ihre Anfrage.

Hinweise für sichere Wiederholungsversuche

  • Wählen Sie einen Wert wie eine Bestellnummer, den Sie bei der Wiederholung desselben Vorgangs erneut verwenden können. Ein neuer Wert bei jedem Versuch lässt sich nicht der früheren Anfrage zuordnen.
  • Wenn keine Antwort eintrifft, wiederholen Sie die Anfrage mit derselben Kennung und demselben Inhalt. Bei geändertem Inhalt verwenden Sie eine neue Kennung.
  • Wie Sie auf HTTP 409 reagieren, hängt von der Ursache ab. Bei laufender Verarbeitung versuchen Sie es später erneut. Bei wiederverwendeter Kennung oder gleichzeitiger Änderung prüfen Sie die Anfrage.