Retry safely with the SMS API

Do you send text messages through our API and occasionally get a timeout or a network error? Then you don't know whether the message has already gone out. If you try again, the recipient may receive the same SMS twice. With the new idempotency_key parameter in version 2 of the SMS API, that can no longer happen.

How does it work?

When sending, pass a unique value in idempotency_key, for example a UUID, one per message. If you send the same request again with the same key within 24 hours, we send nothing. You simply get the original response back, with the same msgid, the same uuid and the same timestamp. In that case the response also contains the header Idempotency-Repeat: true, so you know it was a repeat.

The parameter is optional. If you don't pass it, nothing changes for your existing integration.

Good to know

• A key stays valid for 24 hours from the first request. After that it counts as new and the message is sent again.
• Keys are scoped to your account: another customer can use the same value without any conflict.
• If you use the same key for a different message, with a different number, text or sender, we refuse the request with code 20.
• If a repeat arrives while the first request is still being processed, you get code 21. Just try again a little later.
• If a request was refused, for example because there were not enough credits, we don't store the key. After topping up, simply try again with the same key.
• A key can be at most 255 characters long. If it is longer, you get code 19.

All details are in the API documentation, under sending a message.