Skip to main content
Elke geauthenticeerde POST op de Current API accepteert een Idempotency-Key-header. Wanneer een verzoek met een sleutel slaagt, wordt de respons 24 uur bewaard. Een nieuwe poging met dezelfde sleutel speelt de bewaarde respons opnieuw af in plaats van het verzoek opnieuw uit te voeren. Zo kun je veilig een verzoek opnieuw proberen dat aan jouw kant een time-out of fout gaf, zonder risico op een dubbele afschrijving, overboeking of resource. Elke unieke string tot 255 bytes werkt als sleutel. Een UUID is een goede standaardkeuze. Genereer voor elke afzonderlijke bewerking een nieuwe sleutel en hergebruik precies die sleutel alleen om die bewerking opnieuw te proberen.
Opnieuw afgespeelde responsen zijn byte voor byte identiek aan het origineel, inclusief de statuscode, en bevatten een Idempotent-Replayed: true-header, zodat je een herhaling kunt onderscheiden van een nieuwe uitvoering.
Foutresponsen worden ook opnieuw afgespeeld. Als het oorspronkelijke verzoek mislukte met een 4xx, retourneert een nieuwe poging met dezelfde sleutel diezelfde fout. Die mislukking was de werkelijke uitkomst van het verzoek. Stuur in plaats daarvan een nieuwe sleutel met het gecorrigeerde verzoek.
Een paar details die goed zijn om te weten:
  • “Zelfde verzoek” betekent dat de methode, het pad, de querystring, de body en Api-Version-Date allemaal exact overeenkomen met het origineel. Elk verschil wordt behandeld als hergebruik van de sleutel en geweigerd met een 400 waarvan de error.code idempotency_key_mismatch is.
  • Sleutels zijn gebonden aan de geauthenticeerde aanroeper. Twee verschillende API-sleutels of gebruikers kunnen dezelfde sleutelwaarde gebruiken zonder dat die botsen.
  • De header wordt genegeerd bij niet-geauthenticeerde verzoeken en bij andere methoden dan POST. GET-, PATCH- en DELETE-verzoeken kun je veilig opnieuw proberen.
  • Zolang het eerste verzoek met een sleutel nog loopt, retourneert een nieuwe poging een 409 waarvan de error.code idempotency_request_in_progress is. Als het eerste verzoek mislukte met een onbekende uitkomst (bijvoorbeeld een servercrash halverwege het verzoek), blijven nieuwe pogingen die 409 retourneren totdat de sleutel verloopt. De API loopt nooit het risico een verzoek twee keer uit te voeren.