Idempotency

Wie zu verwenden

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key ist ein beliebiger String bis zu 64 Zeichen, der für jede logische Operation einzigartig ist. Empfohlen: ULID oder UUID v4.

Garantien

• Innerhalb von 24 Stunden nach der ersten Anfrage mit diesem Schlüssel geben wiederholte Anfragen mit demselben Schlüssel dieselbe Antwort zurück, ohne erneute Berechnung und ohne Abrechnung von Credits.
• Wenn der Anfragetext vom Original abweicht: wird 409 Conflict mit dem Code idempotency_key_reuse zurückgegeben.
• Nach 24 Stunden wird der Schlüssel vergessen, eine neue Anfrage mit demselben Schlüssel wird normal behandelt.

Hinweis

Idempotenz ist ein Schutz vor Doppelbelastung bei Netzwerkausfällen, kein Cache. Für Caching verwende den nativen X-Cache-Mechanismus (5 Minuten, siehe Kredite und Limits).

Wann es benötigt wird

• In Webhook-Handlern, bei denen der Retry von einem externen System kommt (z.B. ein Zahlungsanbieter oder CRM sendet ein Ereignis, das du analysierst und eine Berechnung durchführst)
• In Hintergrund-Jobs, bei denen Retry das Standardverhalten bei Ausfällen ist
• In CI/CD-Pipelines, bei denen Tests erneut ausgeführt werden können

Für normale Interaktionen wie “Benutzer klickt auf Button → Karte wird angezeigt” ist Idempotenz nicht erforderlich - der Benutzer sieht das Ergebnis sowieso, und Doppelklicks kommen normalerweise nicht vor.

Wann es nicht verwendet werden sollte

• Setze keinen Schlüssel, um bei gleichen Anfragen Credits zu sparen: dafür gibt es X-Cache (kostenlos, 5 Minuten)
• Generiere keinen Schlüssel aus hash(body): dann verlierst du das Standardverhalten von Idempotency-Key (wiederholtes 409 bei Abweichung des Body)