Een API-verzoek kan opnieuw worden verstuurd doordat een client een time-out krijgt, een gebruiker herhaald klikt of een netwerkverbinding wegvalt. Met idempotentie kan een API zulke herhalingen verwerken zonder dezelfde bewerking onbedoeld opnieuw uit te voeren. Dit artikel behandelt idempotency keys, opslag van verzoekstatus, gelijktijdige verzoeken en de grenzen van deze aanpak.
Wat idempotentie in een API wel en niet betekent
Je spreekt van idempotentie bij een bewerking als herhalen met exact dezelfde invoer op het eind precies hetzelfde resultaat geeft als eenmalig uitvoeren. Dat hoeft niet te betekenen dat je altijd dezelfde HTTP-response ziet. Stel je doet een POST die een bestelling aanmaakt: het eerste verzoek retourneert een nieuw object, een tweede keer krijg je gewoon het bestaande terug. Want zolang de onderliggende data niet telkens verder verandert, voldoet het.
HTTP-methoden geven richting. Een GET mag geen database wijzigen. Een PUT moet meestal één resource vervangen, niet optellen of bijschrijven. POST is standaard niet idempotent: nog een keer sturen leidt vaak tot twee afzonderlijke transacties of inschrijvingen. Maar je maakt een POST alsnog idempotent als je het verzoek herkent aan een idempotency key en de originele uitkomst bewaart (zie Stripe of Mollie voor praktijkvoorbeelden).
Let op, idempotentie is heel wat anders dan exactly-once delivery. Het netwerk geeft geen garantie dat je client weet of een request is aangekomen, zeker niet bij time-outs of verbroken connecties. Achter de schermen kan de actie allang zijn uitgevoerd, terwijl de response nooit arriveert. Dus: idempotentie zorgt er puur voor dat het veilig wordt om te herhalen; het verslaat duplicaten niet automatisch. Spreek altijd af: welke acties worden beschermd, wat maakt een bewerking "dezelfde", hoe lang is een key geldig? Zonder die grenzen is "idempotent" vooral een wens, geen contract. Zelf API-koppelingen bouwen? Lees over API-koppelingen en automatisering.
Waarom time-outs en retries dubbele bewerkingen veroorzaken
Als een client een time-out krijgt, weet je niet of de server het verzoek heeft verwerkt. Misschien was de database al aangepast toen de verbinding uitviel. Dus nog een keer sturen (retry) is logisch vanuit beschikbaarheid, maar zonder idempotentie krijg je gewoon een tweede order, dubbele e-mails of twee keer een betaling.
Dubbele uitvoering kan ontstaan door veel meer dan een retry in je code. Een mobieltje dat het netwerk verliest levert bij reconnect soms nog een keer, bepaalde proxies dienen hetzelfde verzoek nog eens aan en echte mensen drukken gerust opnieuw op een knop als zichtbare feedback uitblijft. Ook message queues werken volgens "at least once": beter een keer te veel afleveren dan een bericht stil verliezen. De ontvangende API moet hierop voorbereid zijn.
Een goed retrybeleid valt of staat met idempotentie. Bijvoorbeeld: exponential backoff helpt tegen overbelasting, maar lost race conditions niet magisch op. Gebruik voor dezelfde logische actie altijd exact dezelfde idempotency key bij elke poging. Als je steeds een nieuwe key stuurt, vraag je per definitie steeds een nieuwe bewerking aan. En spreek af: wanneer mag een client opnieuw aanbieden, welke foutcodes betekenen retryen, hoe lang blijft een key geldig? Alleen dan reageren client en server eenduidig op herhaling. Lees ook over API-rate limits en veilig opnieuw proberen.
Idempotency keys kiezen en aan verzoeken koppelen
Een idempotency key is een unieke code voor één logische mutatie. Voordat je überhaupt het verzoek verstuurt, maak je de key aan (vaak gewoon een UUID), zodat retries niet per ongeluk een tweede bewerking starten. Kies geen key die alleen uit het account of actie-naam bestaat: dat voorkomt niet per ongeluk botsende bewerkingen.
De scope van de key vraagt aandacht. Je kunt uniek maken per gebruiker, client, route, of juist granulair per payload. Te ruim maakt ongewenste samenloop mogelijk, te smal accepteert duplicaten onder dezelfde key. Tip: combineer de key met unieke gebruikers- of clients-ID’s en de context van de bewerking. Authenticatie blijft gewoon nodig, want een key is geen toegangsbewijs.
De server moet herkennen of een key met exact dezelfde actie is hergebruikt. Bewaar daarom tenminste een hash van methode, URL en requestbody. Bestaat de key al, maar de inhoud wijkt af, stuur dan een foutmelding terug. Vergelijk payloads zorgvuldig; kleine verschillen in valuta of headers kunnen inhoudelijk belangrijk zijn. Je behandelt de key als zwart kastje: de interpretatie en houdbaarheid horen serverkant. Zet dat vast voor clients, integraties en SDK’s, dat voorkomt verwarring bij implementatie. Voor maatwerk aan de serverkant kun je terecht bij een PHP developer.
Verzoekstatus opslaan zonder race conditions
Idempotentie werkt alleen als je de relatie tussen key, verzoek en resultaat bewaart. In je database noteer je scope, key, hash van de request, status, responseinfo en timestamps. Zet altijd een unieke constraint op scope + key. Eerst opzoeken en daarna inserten is niet veilig genoeg; twee gelijktijdige processen kunnen dan allebei passeren.
Pak het liever zo aan: claim de key met één insert die faalt als de key al bestaat dankzij de databaseconstraint. Alleen de winnaar voert de opdrachten uit. De tweede tegen dezelfde key ziet: deze is al in gang, en leest de status terug. Is de eerste actie nog bezig, kan de API wachten, een status teruggeven of een retrybare fout sturen. Afhankelijk van je use-case: lang wachten vreet connecties, direct antwoorden vraagt dat de client later kan poll-en of opnieuw probeert bij een foutmelding.
Belangrijk: koppel registratie van de key en de mutatie aan elkaar, liefst hetzelfde transactiedomein. Slaat een crash tussen beide toe, dan zou je inconsistentie krijgen (actie uitgevoerd maar status onbekend). Staat alles in dezelfde database, zet het samen in een transactie. Bij externe systemen gaat dat niet, daar zijn extra overgangen of recovery-processen nodig. Geef aan hoe je een half-afgehandeld statusrecord oplost na crash. Gebruik eventueel een lease met timeout zodat vastgelopen claims weer vrijkomen, maar voorkom dat oude processen alsnog beginnen (fencing beschermt daartegen).
Statusovergangen en opslag van de response
Alleen registreren dat een key "al gezien is" is niet genoeg. Je moet weten of de operatie loopt, klaar is of is gefaald. Veel projecten werken met processing, completed en failed als statussen, in vaste overgangsvolgorde. Een gedeeltelijk record mag je nooit als succesvol uitleggen, anders ziet de client een OK terwijl in de backend niks gebeurde.
Na afronden bewaar je statuscode en response-body. Bij een retry krijgt de client dan precies dezelfde response, zonder dat de mutatie opnieuw gebeurt. Grote uitkomsten kun je beperken tot noodzakelijke velden of een pointer naar het eindresultaat. Let op headers: request-IDs, timestamps en cookies zijn vaak dynamisch. Niet alles moet blind worden herhaald, bepaal welke response-onderdelen vastliggen en welke per poging anders horen te zijn.
Fouten moet je apart behandelen. Validatiefouten vóór de mutatie kun je soms opnieuw beoordelen, maar maak het onderscheid expliciet als je bij dezelfde key iets met andere invoer toestaat. Een fout na een gedeeltelijk gelukt extern effect vraagt om registratie: niet zonder verder onderzoek nog eens uitvoeren. Zet definitieve fouten apart, werk met een status voor tijdelijke mislukking of herstel. Antwoord bij een retry zichtbaar anders op een lopend verzoek, een gecontroleerd gefaalde poging, of een onbekende situatie. Daarmee voorkom je dat clients gissen hoe te reageren bij een 5xx-fout.
Database-transacties en gelijktijdige verzoeken
Met een unieke key voorkom je dubbele registratie, maar de volgorde waarin je database-opdrachten uitvoert blijft bepalend. Claimen, muteren, voltooien: idealiter allemaal binnen dezelfde transactie. Gaat het mis tijdens het proces, dan rolt de database netjes alles terug: geen half werk opgeslagen dus. Dit lukt vooral met solide relationele databases; als alles buiten hetzelfde domein valt, is het lastiger.
Hou transacties kort. Als je tijdens een langlopende taak (zoals een kroonverwerking of externe call) de transactie openhoudt, blokkeert dat resources. Soms dus eerst status processing wegschrijven, daarna pas iets uitvoeren. Je hebt dan wel herstel-logica nodig voor processen die stukgaan, en bescherming voor meerdere workers die willen starten. Leases, CAS-updates of transactionele tokens zijn hiervoor inzetbaar, ontwerp het protocol in samenhang.
Zie je gelijktijdig dezelfde key binnenkomen op geschaalde servers? Lokaal locken heeft geen zin: alleen een centrale constraint of gedeeld subsysteem werkt op schaal. Bijvoorbeeld: Redis voor snelle samenwerking, maar let op, een tijdelijke cache is niet veilig als dubbele externe handelingen fatale gevolgen hebben. Kies dus bewust, met het isolatieniveau en deadlocks in het vizier. Vang conflicts correct af, convert naar een vaste response, en log wat relevante context inclusief de key (anoniem of versleuteld als dat nodig is).
Externe effecten, message queues en outboxpatronen
Twee acties tegelijk regelen, database committen én een externe dienst aanroepen, kan niet als atomaire stap. Commit je eerst de database en crasht het proces, dan mist je externe provider de actie. Doe je het andersom, kan je database het effect niet loggen als die daarna faalt. Herhalen van de aanvraag kan dus dubbel extern effect geven, zelfs als je interne kant idempotent bouwt.
Werk je met downstreamdiensten zoals Stripe, verstuur een afgeleide idempotency key mee. Geef dezelfde logische waarde mee, niet elke retry een nieuwe key. Bekijk goed: hoe lang bewaart die provider de key, waarmee vergelijkt deze, en wat gebeurt er als de inhoud verschilt per key? Ondersteunt je provider geen idempotentie, ga dan niet blind herhalen, maar raadpleeg eerst de status of stem af via reconciliatie. Voor integraties rond betalingen zijn er ook Mollie API-integraties en maatwerk betaalmethoden.
Gebruik je het outboxpatroon, dan schrijf je mutaties en een event of bericht in één database-transactie weg. Losse worker(s) lezen later de outbox en publiceren naar bijvoorbeeld Kafka, waarna het event als afgehandeld wordt gemarkeerd. Ook hier: publish en markeren kunnen overlappen, dus de uiteindelijke ontvanger moet tegen dubbele levering kunnen. Geef ieder event een unieke ID, leg een inboxlog aan. Je streeft zo niet naar exactly-once, maar naar expliciet herstelbaar gedrag bij twijfel. Registreer per stap de correlatie-ID en status zodat je inzage hebt bij twijfels of mogelijk schadegevende uitkomsten na duplicaten.
Vervaltijd, beveiliging en tests voor idempotentie
Je wilt idempotency-records niet onbeperkt vasthouden: dat is duur en kan privacyproblemen geven als er gevoelige info meesluipt. Maar, te vroeg verwijderen is link: een trage retry kan zo onbedoeld alsnog een nieuwe bewerking triggeren. Bepaal de bewaartermijn op basis van de langste retrywindow van je clients, message queues en het risico van een dubbele actie. Wil je langdurig dedupliceren voor cruciale transacties? Bewaar dan een bedrijfskenmerk buiten de tijdelijke idempotency-storage.
Leg alleen die velden vast die je nodig hebt om gelijke verzoeken te herkennen en het juiste resultaat terug te geven. Soms volstaat een hash (let op: canonieke serialisatie is dan essentieel en een hash alleen is geen panacee tegen aanvallen met voorspelbare input). Geef toegang tot idempotency-records alleen aan geautoriseerde gebruikers. Behandel de key niet als API-geheim of token. Denk om limieten op lengte en payload: voorkomt abuse.
Testen vraagt niet alleen om verkeersscenario’s, maar vooral om herhaling en simultaan gebruik. Probeer: twee keer exact hetzelfde verzoek, dezelfde key met iets andere payload, twee verzoeken tegelijk, reconnect na time-out, crash tussen status-updates. Kijk ook wat er gebeurt als de bewaartermijn voorbij is. Monitor in productie op frequentie van duplicate-requests, lock-conflicten en downstream-retries. Log keys waar mogelijk gepseudonimiseerd. Zo merk je afwijkend retrygedrag snel op en kun je bijsturen vóórdat het impact heeft. Lees ook over logging en foutafhandeling bij automatiseringen.
Veelgestelde vragen
Hoe lang moet een API een idempotency key bewaren?
Bewaar een idempotency key zo lang als nodig is om te voorkomen dat een oude retry als nieuwe bewerking wordt gezien. Kijk naar hoe lang clients, jobworkers en tussenlagen kunnen herhalen, en hoe schadelijk een dubbele uitvoering zou zijn. Veel korter houden scheelt opslag, maar geeft kans op vreemde bugs bij late retries. Wil je maximaal veilig zijn (bijvoorbeeld bij transacties)? Overweeg dan een extra controle op een bedrijfskenmerk nadat de key is verlopen.
Hoe behoudt een mobiele app dezelfde idempotency key na een herstart?
Een mobiele app moet de gebruikte idempotency key lokaal bijhouden zolang een actie nog niet definitief is afgerond. Dus: sla de key samen met de actie zelf lokaal op, zodat de app na herstart of netwerkherstel dezelfde key weer kan meesturen. Pas wissen als je server bevestigt dat de handeling volledig klaar is, of de gebruiker annuleert. Een nieuwe, op het oog identieke actie? Toch altijd een nieuwe key maken.
Welke HTTP-statuscode geef je terug als hetzelfde verzoek nog wordt verwerkt?
Stuur bij een nog lopende verwerking duidelijk een response terug die aangeeft dat de uitkomst ontbreekt. 202 Accepted is gangbaar, liefst met een endpoint om de status op te vragen. Heb je geen status-API, gebruik dan bijvoorbeeld Retry-After bij een tijdelijke foutmelding. Geef één duidelijk gedrag en leg dat vast, zodat clients weten wat ze mogen verwachten. Verstuur pas een definitieve status als het resultaat echt vaststaat.
Is een idempotency key een geheim dat een client moet beschermen?
Een idempotency key is geen toegangsbewijs, en hoeft dus niet als geheim te worden behandeld. Elke request moet gewoon via de gebruikelijke authenticatie en autorisatie gaan. Zorg wel dat de key puur als herkenningstoken werkt: stop er geen persoonsgegevens of gevoelige info in, houd ze redelijk kort en log ze niet zomaar. Zo wordt misbruik en data-exposure beperkt.
Hoe maak je een batch-API idempotent als sommige items mislukken?
Bepaal bij een batch-API of je per batch of per item idempotentie wilt, dat hangt af van je ontwerp. Een atomaire batch krijgt één key en herhalen geeft exact het eerder vastgelegde batchresultaat terug. Verwerk je deelsucces, kies dan vaak een key per item: geslaagde gaan niet nog een keer, mislukte kun je opnieuw aanbieden. Zet per item een herkenbare ID en status in de response, en leg vast wat er gebeurt bij wijzigingen tussen tries.
Foto: Anna Tarazevich