Na een API-time-out mag je pas opnieuw schrijven wanneer je hebt gecontroleerd of de eerste opdracht bij het doelsysteem is aangekomen. Een time-out betekent dat jouw applicatie geen definitief antwoord kreeg; het betekent niet dat AFAS, een vervoerder of betaalprovider niets heeft uitgevoerd. Blind herhalen kan precies de dubbele boeking veroorzaken die een retry moest oplossen.
Onzeker is een eigen processtatus
Er zijn drie fundamenteel verschillende uitkomsten: bevestigd mislukt, bevestigd geslaagd en onzeker. Alleen de eerste is direct geschikt voor een gewone herhaalpoging. Bij een onzekere schrijfopdracht kan de server de opdracht hebben verwerkt en pas daarna de verbinding hebben verloren. Markeer zo’n poging expliciet als “uitkomst controleren” en blokkeer afhankelijke vervolgacties totdat de waarheid is vastgesteld.
Leg vóór de POST vast wat je gaat schrijven: werkruimte, order, actie, deterministische referentie en een beperkte hash of snapshot van de zakelijke inhoud. Dat registratiepunt is belangrijk. Als het proces crasht na verzenden maar vóór opslaan van het antwoord, weet de hersteller nog steeds welke externe identiteit hij moet zoeken.
Runbook: bewijs vóór retry
- Bevries automatisch herhalen. Voorkom dat meerdere workers tegelijk dezelfde onzekerheid behandelen.
- Zoek op deterministische identiteit. Gebruik een unieke orderreferentie, boekingssleutel of provider-ID; match niet op alleen bedrag en datum.
- Vergelijk inhoud. Een gevonden record met dezelfde sleutel maar andere regels is een conflict, geen succes.
- Leg het bewijs vast. Bewaar welke bron bevestigde dat de opdracht wel of niet bestaat.
- Kies één vervolg. Bestaand record koppelen, veilig opnieuw aanbieden of menselijk onderzoek.
Dit is een concrete verdieping op algemene idempotentie. Bij een WooCommerce-AFAS-koppeling moet vooral de zakelijke referentie door de hele route herkenbaar blijven.
Fictief voorbeeld: antwoord verloren na boeking
Fictief voorbeeld: woonwinkel Lumenhuis stuurt een financiële boeking met referentie LH-2026-00918 naar AFAS. De verbinding valt na dertig seconden weg. De client ziet een time-out, maar AFAS heeft de boeking al opgeslagen. De status wordt “onzeker”; de volgende automatische poging blijft geblokkeerd.
Een herstelstap vraagt AFAS gericht naar LH-2026-00918. Het record bestaat en regels, bedrag en debiteur komen overeen met de vooraf opgeslagen snapshot. De integratie koppelt de externe identiteit aan de oorspronkelijke poging en markeert haar voltooid. Er volgt geen tweede POST. Was geen record gevonden en was de zoekactie zelf betrouwbaar voltooid, dan kon één gecontroleerde retry worden vrijgegeven. Dit voorbeeld is fictief; de kern is dat technische afwezigheid van een antwoord niet als zakelijke afwezigheid van een record wordt geïnterpreteerd.
Ontwerpkeuzes die herstel mogelijk maken
| Keuze | Waarom nodig |
|---|---|
| Deterministische externe referentie | Maakt gerichte ontvangstcontrole mogelijk |
| Registratie vóór verzenden | Overleeft crash tussen request en response |
| Vergrendeling per deelstap | Voorkomt concurrerende herstelpogingen |
| Inhoudsvergelijking | Voorkomt koppelen aan een toevallig gelijk record |
| Zichtbare onzekerheid | Geeft operations een andere actie dan gewone fout |
Connect kan zulke providerstappen met status en auditspoor modelleren. In Desk kan de medewerker vervolgens zien of een record is bevestigd, nog wordt onderzocht of veilig opnieuw mag worden aangeboden. Vermijd in klantcommunicatie de zin “de boeking is mislukt” zolang de uitkomst werkelijk onzeker is.
Oefen het runbook met kunstmatige storingen. Breek de verbinding één keer vóórdat de provider het verzoek ontvangt, één keer tijdens verwerking en één keer nadat het doelrecord is gemaakt maar vóór het antwoord terugkomt. Die drie gevallen zien aan de clientkant mogelijk hetzelfde uit, maar vragen een andere herstelbeslissing. Controleer of het systeem na een herstart de vooraf opgeslagen intentie terugvindt en of twee herstelworkers door vergrendeling niet tegelijk handelen. Geef handmatige operators geen vrije “nogmaals verzenden”-knop zonder eerst het verificatieresultaat te tonen. Wanneer een provider geen betrouwbare zoekmogelijkheid biedt, moet het proces conservatiever worden: langere observatie, expliciete menselijke controle of een unieke referentie in een later beschikbaar rapport. Onzekerheid verdwijnt niet door een technisch retrybeleid te verbergen.
Noteer per provider welke leesroute als voldoende bewijs geldt en hoe lang gegevens daar zichtbaar worden. Een onmiddellijke zoekactie kan door vertraagde indexering nog niets vinden. Dan is “niet gevonden” evenmin definitief en hoort een tweede, uitgestelde controle vóór de retry.
Wil je retries veilig maken voor jouw financiële of logistieke API’s? Laat één onzekere-write-scenario met Yindle uitwerken.