Idempotency
Networks drop responses. An Idempotency-Key lets you retry any POST without sending — or paying for — the same SMS twice.
How it works
Add an Idempotency-Key header to any POST — /sms/send, /sms/otp/send or /sms/otp/verify. The key is 1–200 printable ASCII characters and is remembered for 24 hours, scoped to your API client.
We fingerprint the request (method, path and body). When the first request finishes successfully, its response is stored. Any retry with the same key and the same body gets that stored response back — nothing is sent or billed again.
Possible outcomes
| Situation | Result |
|---|---|
| First request with this key | Processed normally. |
| Same key, same body, first request finished | The original status and body, with header Idempotent-Replayed: true. |
| Same key, same body, first request still running | 409 idempotency_conflict with Retry-After: 1. |
| Same key, different body | 409 idempotency_conflict. |
| First request returned 4xx or 5xx | Not stored. Fix the problem and retry with the same key. |
Example
# Safe to run twice — the second call replays the first response
curl https://api.smsray.in/api/sms/v1/sms/send \
-H "x-api-key: $SMSRAY_API_KEY" \
-H "content-type: application/json" \
-H "Idempotency-Key: order-1042-shipped" \
-d '{ "to": "9779801234567", "text": "Your order #1042 has shipped." }' -iChoosing keys
- Derive the key from the business event, not from the attempt:
order-1042-shipped,invoice-88-reminder-1. - A random UUID also works if you generate it once and reuse it for every retry of the same message.
- Never reuse a key for a different message — you will get 409 or, worse, the old message's response.
- Keys expire after 24 hours, so don't rely on them to de-duplicate across days.