SMS

Safe retries

Repeat a send after a timeout without texting anyone twice.

When a request times out you can’t know whether it went through. Sending it again might text your customer twice. An idempotency key makes repeating safe.

How it works

Add an Idempotency-Key header to a send: any unique text up to 200 characters. Build it from what the message is about, such as the order and the event.

bash

curl -X POST https://api.falconzo.com/v1/sms/messages \
  -H "Authorization: Bearer $FALCONZO_API_KEY" \
  -H "Idempotency-Key: order-1042-shipped" \
  -H "Content-Type: application/json" \
  -d '{"to": "0771234567", "message": "Your order #1042 has shipped."}'

The first request sends. Any repeat with the same key returns the first answer with "replayed": true and sends nothing.
If the first request is still running when the repeat arrives, the repeat gets 409 with IDEMPOTENCY_IN_PROGRESS. Wait a few seconds and repeat it again.
Keys are separate for test and live keys, so the same key can be used in both.

A key belongs to the first request that used it. Reusing a key for a different message returns the first message’s result and does not send the new one, so make keys unique.