Idempotency
Retry any send without sending, or charging, twice.
Networks fail. A request can reach us and its response never reach you. Without protection, retrying it sends the messages a second time and charges you twice.
Send an Idempotency-Key header with POST /sms and POST /email, and a retry is always safe:
curl https://api.softlinksms.co.ke/api/v1/sms \
-H "X-Api-Key: $SOFTLINK_API_KEY" \
-H "Idempotency-Key: 5d3c1f2e-8a6b-4c0d-9e7f-1a2b3c4d5e6f" \
-H "Content-Type: application/json" \
-d '{"recipients": ["+254712345678"], "body": "Your order has shipped."}'How it works
| You send | You get |
|---|---|
| A new key | The request runs normally, and its response is stored against the key. |
| The same key and the same body, within 24 hours | The stored response, with header Idempotent-Replayed: true. Nothing is sent or charged again. |
| The same key with a different body | 422 idempotency_key_reused. |
| The same key while the first request is still running | Your request waits for the first to finish, then gets its response. Rarely, 409 idempotency_in_progress; retry after a second. |
| No key | The request runs every time. |
A request that fails (for example 402 insufficient_balance, or a validation error) doesn't store a result, so you can fix the cause and retry with the same key.
Choosing keys
- One key per logical send. A login code, a receipt, or chunk 3 of a campaign. Reuse it only when retrying that same send.
- Make it meaningful or random. Your own record id (
otp-<verification id>,receipt-INV-0042) makes keys easy to reason about. A UUID v4 works too. - Up to 255 characters.
- Keys are per account and per endpoint. The same key on
/smsand/emailare independent. - Keys expire after 24 hours. After that, the same key starts a new send.
When to send a key
Always, for anything you'd retry. It costs nothing, and it's the difference between a retry and a double charge.