Idempotency

Alle endpoints van de AstroWay API zijn van nature idempotent: dezelfde input geeft altijd dezelfde output, geen bijwerkingen (behalve het aftrekken van credits en het loggen van usage).

Dit betekent dat een retry bij netwerkfouten veilig is. Maar om te voorkomen dat een herhaald verzoek credits twee keer aftrekt, moet je de Idempotency-Key header meesturen.

Hoe te gebruiken

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 - een willekeurige string tot 64 tekens, uniek voor elke logische operatie. Aanbevolen: ULID of UUID v4.

Garantie

Gedurende 24 uur na het eerste verzoek met deze sleutel, geven herhaalde verzoeken met dezelfde sleutel exact dezelfde response terug, zonder herberekening en zonder credits af te trekken.
Als de body van het verzoek verschilt van het origineel: wordt 409 Conflict geretourneerd met de code idempotency_key_reuse.
Na 24 uur wordt de sleutel vergeten, een nieuw verzoek met dezelfde sleutel wordt normaal.

Wanneer dit nodig is

In webhook-handlers waar een retry komt van een extern systeem (bijvoorbeeld een payment-provider of een CRM die een gebeurtenis stuurt die jij parseert en verwerkt)
In achtergrondjobs waar retry de standaardgedrag is bij fouten
In CI/CD pipelines waar een test opnieuw kan worden uitgevoerd

Voor gewone interacties zoals “gebruiker drukt op een knop → kaart wordt getoond” is idempotentie niet nodig – de gebruiker ziet het resultaat toch, er zijn meestal geen extra klikken.

Wanneer niet te gebruiken

Stel geen sleutel in om credits te besparen op identieke verzoeken: daarvoor is er X-Cache (gratis, 5 minuten)
Genereer geen sleutel uit hash(body): dan verlies je het standaardgedrag van Idempotency-Key (herhaalde 409 bij een afwijkende body)

Nuttig?

Wijziging voorstellen

Laatst bewerkt: 29 sep 2026