Retry safely with idempotency keys
Every request that spends money takes a key, honoured for 24 hours, and a retry replays the original response verbatim.
The hard case in messaging is not the request that fails. It is the one that succeeds and whose response you never see. Without a key, your retry sends a second message; with one, it returns the first response byte for byte, and the customer receives one message.
curl -X POST https://api.woyra.io/v1/messages \
-H "Authorization: Bearer $WOYRA_KEY" \
-H 'Idempotency-Key: order-4821-otp' \
-H 'Content-Type: application/json' \
-d '{"channel":"sms","to":"+251911234567","from":"WOYRA","body":"Your code is 483920"}'Choosing a key
- Derive it from the thing the send is about, and store it with that thing: order-4821-otp, invoice-991-receipt.
- Generate it once, before the first attempt, and reuse it for every retry of that attempt.
- Never derive it from the clock, or from anything that changes when you rebuild the body.
What the two conflicts mean
- idempotency_conflict: this key was used with a different body. That is a bug in your code, not a transient failure, and a new key is the fix.
- idempotency_in_progress: the first attempt is still running. Wait briefly and retry; you will get its answer.
Retry on these, and nothing elseRetry 429 after the Retry-After header says, 503 route_unavailable with backoff, and 500. A 4xx other than 429 will fail again identically, and retrying it only makes your logs harder to read.
Questions
How long is a key remembered?
24 hours, which is far longer than any sensible retry window.
Is the key required?
On requests that spend money, yes. It is required rather than optional exactly because the endpoint spends money, and an optional safety mechanism is one that is missing when it matters.
Next
Verify a webhook signatureTen lines, in the language you already use. An unverified webhook is an endpoint anyone on the internet can post to.Send your first emailFrom nothing to a delivered email, with the DNS explained rather than assumed.
Get a test key and run any of this in about ninety seconds.