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?

Je stelt een Idempotency-Key-header in voor elke beoogde SMS-verzending en hergebruikt die wanneer je het identieke verzoek opnieuw probeert. Wanneer Bird het oorspronkelijke antwoord bewaart, geeft een overeenkomende nieuwe poging dat antwoord terug zonder de verzending opnieuw uit te voeren.

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. De in-flight-vergrendeling verloopt binnen 30 seconden. Verlopen zegt niets over of de oorspronkelijke verzending effect heeft gehad.
• 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. Bird bewaart geen 5xx-antwoorden. Een nieuwe poging herhaalt een bewaard succesvol antwoord of kan opnieuw worden uitgevoerd als er geen antwoord is bewaard.

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

Garandeert de key dat er geen duplicaten zijn?

De key vermindert dubbele verzendingen, maar garandeert niet dat er maar één uitvoering plaatsvindt.

Een verzending kan effect hebben voordat Bird het antwoord bewaart. Als het bewaren van het antwoord mislukt of de in-flight-vergrendeling verloopt, kan een nieuwe poging de verzending opnieuw uitvoeren. Het bewaarvenster van drie uur beperkt ook de replaybescherming.

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 de key om eventuele beschikbare replaybescherming te benutten.
3. Los conflicten met gewijzigde verzoeken op en stel nieuwe pogingen uit wanneer het oorspronkelijke verzoek nog loopt.
4. Controleer onzekere verzendingen aan de hand van je gegevens, ook die buiten het replayvenster van drie uur vallen, voordat je beslist of een nieuwe verzending gepast is.