Hoe voorkom ik dat ik dezelfde SMS twee keer verstuur?

Een verbinding kan wegvallen nadat Bird een SMS accepteert, maar voordat je applicatie het antwoord ontvangt. Opnieuw proberen met een nieuwe key kan een tweede verzending veroorzaken, omdat Bird het als een apart verzoek beschouwt.

Hoe werkt de key?

Stel een Idempotency-Key-header in voor elke beoogde SMS-verzending en hergebruik die wanneer je het identieke verzoek opnieuw probeert. De garantie van precies één acceptatie betekent dat overeenkomende nieuwe pogingen binnen drie uur naar dezelfde geaccepteerde verzending moeten leiden, ook als je het antwoord daarop bent kwijtgeraakt.

Een orderbevestiging behoudt bijvoorbeeld dezelfde key bij een time-out en de nieuwe poging. Een bevestiging voor een andere order krijgt een andere key.

Herhaalde antwoorden bevatten Idempotency-Replay: true, waarmee je logs een replay van een nieuw verwerkt verzoek kunnen onderscheiden.

SMS-keys zijn gekoppeld aan je werkruimte. Bird bewaart afgeronde antwoorden gedurende drie uur onder zijn idempotency-contract. Na dat venster kan dezelfde key een nieuw verzoek uitvoeren, omdat het replayrecord is verlopen. Een nieuwe poging een dag later vereist daarom controle van de oorspronkelijke uitkomst aan de hand van je gegevens voordat je opnieuw verstuurt.

Wat vertellen de foutantwoorden me?

De foutcode onderscheidt een gewijzigd verzoek, een onafgerond verzoek en niet-beschikbare bescherming.

• 409 met E01005 IdempotencyKeyReuse: dezelfde key is gebruikt voor een ander verzoek. Corrigeer de key-toewijzing voordat je het opnieuw probeert, want deze key hoort bij het oorspronkelijke verzoek. Bird vergelijkt de methode, het endpoint, het pad en de queryparameters, en de onbewerkte body. Zelfs een JSON-verschil in witruimte maakt het verzoek anders.
• 409 met E01004 RequestInProgress: een gelijktijdig verzoek met dezelfde key is nog niet afgerond. Wacht even en probeer opnieuw met dezelfde key en hetzelfde verzoek, zodat het oorspronkelijke verzoek kan voltooien.
• 503 met E01033 IdempotencyUnavailable: bescherming was niet beschikbaar vóór uitvoering, dus deze poging is niet uitgevoerd. Probeer opnieuw met backoff en dezelfde key en hetzelfde verzoek. Dit antwoord zegt niets over de uitkomst van een eerdere poging.
• Andere 5xx-antwoorden of time-outs: probeer opnieuw met backoff en dezelfde key en hetzelfde verzoek. De garantie van precies één acceptatie dekt deze nieuwe pogingen binnen drie uur. Stop wanneer je budget voor nieuwe pogingen op is.

De idempotency-header behoudt de identiteit van het verzoek bij al deze nieuwe pogingen.

Garandeert de key dat er geen duplicaten zijn?

De garantie is precies één acceptatie voor identieke verzoeken met dezelfde key in dezelfde werkruimte binnen drie uur. Die nieuwe pogingen moeten naar één geaccepteerde verzending leiden, ook na een verloren antwoord. Controleer de berichtstatus om de aflevering te bevestigen.

Na het bewaarvenster van drie uur kan de oorspronkelijke key een nieuwe bewerking aanduiden. Controleer een onbekende oorspronkelijke uitkomst voordat je opnieuw verstuurt.

Bewaar de gebeurtenis- en verzendrecords van je applicatie, zodat je je gegevens over een onzekere uitkomst kunt vergelijken voordat je opnieuw verstuurt. Vermeld het order- of referentienummer in het bericht, zodat de ontvanger kan herkennen om welke gebeurtenis het gaat.

Hoe zit het met een bericht dat de telefoon twee keer toont?

Een idempotency-key regelt herhaalde API-verzoeken; hij bepaalt niet hoe de telefoon van een ontvanger een bericht weergeeft. Een screenshot alleen zegt niet waar een duplicaat is ontstaan.

Vergelijk het volledige verzendlog van je applicatie met de berichtrecords van Bird. Meerdere geaccepteerde bericht-ID's kunnen meerdere verzendingen aantonen. Het vinden van slechts één ID in een onvolledig log bewijst niet dat het duplicaat verderop in de keten is ontstaan. Vermeld de relevante ID's, bestemming en tijdstempels wanneer je support vraagt om het te onderzoeken.

Wat moet ik doen?

1. Wijs één key toe aan elke beoogde SMS-verzending en hergebruik het identieke verzoek bij nieuwe pogingen.
2. Probeer netwerkfouten, time-outs en 5xx-antwoorden opnieuw met backoff en behoud binnen drie uur de key en het identieke verzoek.
3. Los conflicten met gewijzigde verzoeken op en stel nieuwe pogingen uit wanneer het oorspronkelijke verzoek nog loopt.
4. Laat uitgeputte of verlopen nieuwe pogingen onopgelost totdat je de uitkomst hebt gecontroleerd, voordat je beslist of een nieuwe verzending gepast is.