Veilig opnieuw proberen met de SMS API
Verstuurt u sms'en via onze API en krijgt u af en toe een time-out of een netwerkfout? Dan weet u niet of het bericht al vertrokken is. Probeert u opnieuw, dan riskeert u dat de ontvanger dezelfde sms twee keer krijgt. Met de nieuwe parameter idempotency_key in versie 2 van de SMS API kan dat niet meer.
Hoe werkt het?
Geef bij het versturen een unieke waarde mee in idempotency_key, bijvoorbeeld een UUID, één per bericht. Stuurt u dezelfde request binnen 24 uur opnieuw met dezelfde key, dan versturen we niets. U krijgt gewoon het oorspronkelijke antwoord terug, met hetzelfde msgid, dezelfde uuid en hetzelfde tijdstip. In dat geval bevat het antwoord ook de header Idempotency-Repeat: true, zodat u weet dat het om een herhaling gaat.
De parameter is optioneel. Geeft u hem niet mee, dan verandert er niets aan uw bestaande koppeling.
Goed om te weten
- Een key blijft 24 uur geldig vanaf de eerste request. Daarna geldt hij als nieuw en wordt het bericht opnieuw verstuurd.
- Keys gelden per account: een andere klant kan dezelfde waarde gebruiken zonder dat dat botst.
- Gebruikt u dezelfde key voor een ander bericht, met een ander nummer, een andere tekst of een andere afzender, dan weigeren we de request met code 20.
- Komt een herhaling binnen terwijl de eerste request nog verwerkt wordt, dan krijgt u code 21. Probeer het dan even later opnieuw.
- Werd een request geweigerd, bijvoorbeeld omdat er te weinig credits waren, dan bewaren we de key niet. Na het opladen probeert u gewoon opnieuw met dezelfde key.
- Een key mag maximaal 255 tekens lang zijn. Is hij langer, dan krijgt u code 19.
Alle details staan in de API-documentatie bij het versturen van een bericht.
