Idempotenz

Warum das wichtig ist

Netzwerk-Timeouts und Client-Retries könnten sonst doppelte Bestellungen oder Tickets erzeugen. Mit demselben Schlüssel und demselben Request-Body liefert die API die gespeicherte erfolgreiche Antwort, statt die Operation erneut auszuführen.

Verhalten

1. Senden Sie pro logischer Operation einen eindeutigen Idempotency-Key (UUID empfohlen).
2. Die API hasht den Request-Body und speichert erfolgreiche 2xx-Antworten für Organisation, Methode, Pfad und Schlüssel.
3. Wiederholung mit demselben Schlüssel und demselben Body → ursprünglicher Status und Body, plus Header Idempotency-Replayed: true.
4. Derselbe Schlüssel mit anderem Body → 409 Idempotenz-Konflikt.

Nicht erfolgreiche Antworten werden nicht für Replay gespeichert. Sie dürfen nach transienten Fehlern mit demselben Schlüssel erneut versuchen, solange der Body identisch bleibt.

Beispiel

curl -X POST https://api.cowtic.com/api/v1/orders \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "evt_…",
    "customer": { "email": "guest@example.com", "name": "Ada Guest" },
    "items": [{ "ticketId": "tt_…", "quantity": 2 }]
  }'

Hinweise für Clients

• Erzeugen Sie den Schlüssel vor dem ersten Versuch und verwenden Sie ihn bei Retries erneut.
• Rotieren Sie den Schlüssel nicht, wenn Sie nur dieselbe Payload erneut senden.
• Verwenden Sie einen neuen Schlüssel für eine neue logische Kauf- oder Ausgabeanfrage.