Retry WhatsApp API sends without double-sending: idempotency keys, timeouts and 429s
How to retry a failed WhatsApp send safely. An Idempotency-Key example in Node, what the API does on a replay, a timeout, a 409 or a 429, and which errors you should never retry. Tested against a local mock.
November 17, 2026 · 6 min read
Your app calls the WhatsApp API, the request times out, and you don't know whether the customer got the message. Retry blindly and they may get it twice. Don't retry and they may get nothing. An idempotency key removes the guess: you send the same key with the same request, and the API does the work once. This guide shows the header, what the API does in each case, and a small Node helper that retries only what is worth retrying.
SendFromChat is an independent product and is not affiliated with Meta or WhatsApp. It runs on Meta's official WhatsApp Cloud API; you keep your own WhatsApp Business account. The behaviour below comes from our REST API reference and from reading our own API code on 17 Nov 2026. Where the docs do not say something, this guide says so.
Tested against a local mock only. We wrote a small mock server that copies the behaviour described here, and ran the helper against it: first send, replay, a 500 then success, a 429 with Retry-After, a 422 that must not be retried, a timeout, and a key reused with a different body. We did not run it against live WhatsApp traffic. Use a test key first.
The header
Add Idempotency-Key to POST /messages, derived from the event in your app, not from the request:
Idempotency-Key: order-4821-shipped
What the API does with it (REST API reference, and our API code):
| What you send | What you get back |
|---|---|
| A new key | The send runs. The response is stored under that key. |
| The same key and the same body again | The first response again, with the header Idempotent-Replayed: true. Nothing is sent a second time. |
| The same key while the first request is still running | 409 with request_in_progress. Wait and ask again. |
| The same key with a different body | 422 with idempotency_mismatch. |
| A key longer than 200 characters | 400 with invalid_request. |
| The first attempt failed with an error | The key is released, so a corrected retry under the same key can run. |
Keys are checked per workspace. We do not document how long a key is kept, so don't rely on an old key to protect you weeks later. Build a key from the event (order-4821-shipped, invoice-9913-reminder-1) so the same event always gets the same key and two different events never share one.
Three ways a key goes wrong
- A random key per attempt.
crypto.randomUUID()inside the retry loop gives each retry a new key, which is the same as having none. Make the key once, outside the loop. - A body that changes between tries. We hash the raw request body. If you rebuild the JSON on every attempt and the key order or spacing differs, you can get
idempotency_mismatchon a retry that meant the same thing. Serialise once and resend the same string. - One key for a whole batch. Each message needs its own key. Reuse one key across different recipients and everything after the first returns
idempotency_mismatch.
What to retry, and what not to
| Response | Retry? | Why |
|---|---|---|
| Timeout or network error | Yes, same key and body | You don't know if it arrived. A replay or a 409 tells you. |
409 request_in_progress |
Yes, after a short wait | The first request is still running. |
429 rate_limited |
Yes, after Retry-After |
In our code the limit is 300 requests a minute per workspace and Retry-After is 60. This limit is not in the REST reference today, so read the header rather than hard-coding it. |
5xx |
Yes, with backoff | A failed attempt releases the key. |
429 warmup_limit |
Not in a loop | A new number has hit today's warm-up cap. Queue it for later (warm-up rules). |
422 opted_out, window_closed, template_not_approved, whatsapp_rejected |
No | These are WhatsApp's rules, so the same request fails the same way. Fix the cause (error codes). |
402 sending_paused |
No | The trial ended or the plan limit is used up. |
400, 401, 403, 404 |
No | The request or key is wrong. |
One honest limit, our reading of the code: if a request fails on our side after Meta has taken the message, the key is released and a retry would run again. If a duplicate would hurt, check GET /messages/{id} or the message.status webhook before you resend (delivery status guide).
The helper
Node 18 or newer, no packages. It serialises the body once, keeps one key for all attempts, retries only the cases above and stops after five tries.
// send-with-retry.mjs (Node 18+)
const BASE = process.env.SFC_BASE ?? "https://sendfromchat.com/api/v1";
const KEY = process.env.SENDFROMCHAT_KEY;
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
// 1s, 2s, 4s, 8s... capped at 30s, plus up to 250ms of jitter
const backoff = (attempt) => Math.min(30_000, 1000 * 2 ** (attempt - 1)) + Math.random() * 250;
export async function sendWhatsApp(body, idempotencyKey, { maxAttempts = 5, timeoutMs = 10_000 } = {}) {
// Serialise ONCE. The API hashes the raw body, so every retry must send the same bytes.
const payload = JSON.stringify(body);
for (let attempt = 1; ; attempt++) {
let res;
try {
res = await fetch(`${BASE}/messages`, {
method: "POST",
headers: {
Authorization: `Bearer ${KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: payload,
signal: AbortSignal.timeout(timeoutMs),
});
} catch (err) {
// Timeout or network error: we don't know if it arrived. Retrying with the SAME key is what makes this safe.
if (attempt >= maxAttempts) throw err;
await sleep(backoff(attempt));
continue;
}
const data = await res.json().catch(() => ({}));
if (res.ok) return { ...data, replayed: res.headers.get("Idempotent-Replayed") === "true" };
const type = data.error?.type;
// Retry only what can change on its own. warmup_limit is a daily cap: queue it for later instead.
const retryable = res.status >= 500 || type === "request_in_progress" || type === "rate_limited";
if (!retryable || attempt >= maxAttempts) {
throw Object.assign(new Error(type ?? `HTTP ${res.status}`), { status: res.status, type });
}
const retryAfter = Number(res.headers.get("Retry-After"));
await sleep(retryAfter > 0 ? retryAfter * 1000 : backoff(attempt));
}
}
Use it like this, with the key built from your own event:
import { sendWhatsApp } from "./send-with-retry.mjs";
const result = await sendWhatsApp(
{
to: "+14155550132",
template: { name: "order_shipped", language: "en_US", variables: ["Ana", "#4821"] },
},
"order-4821-shipped",
);
console.log(result.status, result.replayed); // "accepted" false (true if it was a replay)
202 accepted means Meta accepted the message, not that it arrived. Delivery and read status come afterwards through the message.status webhook (how to track them).
Test it with a test key
A test key (sfc_test_…) runs the same checks as a live send and then stops, so nothing is sent (test guide). Send the same request twice with the same key. The second answer should carry Idempotent-Replayed: true. Then change one field and reuse the key: you should see idempotency_mismatch.
Checklist
- One key per business event, made outside the retry loop.
- The body serialised once and resent unchanged.
- Retry timeouts,
409 request_in_progress,429 rate_limitedand5xx, with backoff and a cap. - Never retry
422,402or4xxrules in a loop. - Track real delivery with
message.status, not the202. - Only message people who agreed to hear from you; opted-out numbers are refused with
opted_out.
A note for EU and UK customers
SendFromChat stores data in Mumbai, India. Transfers from the EU and UK are covered by the Standard Contractual Clauses and the UK Addendum in our Data Processing Agreement, and the sub-processors are listed publicly. Read it before you decide. Your own consent and opt-out records stay your responsibility (GDPR guide). This is not legal advice.
Try it
Start the 30-day free trial (no card), connect a number, create a test key and run the helper against it. Plans start at $19 a month; Meta's per-message charges are billed by Meta to your own account (pricing guide). The same pattern sits under the order notifications guide and the Stripe payment-failed guide.
Sources
- SendFromChat REST API reference:
Idempotency-Key,Idempotent-Replayed,idempotency_mismatch, the error table. Read 17 Nov 2026. - Our API code,
lib/developer/api.ts(key handling, 409, 422, 429 withRetry-After) andapp/api/v1/messages/route.ts. Read 17 Nov 2026.
Do this from your AI assistant
SendFromChat connects Claude, ChatGPT, Cursor or any MCP client to the WhatsApp Business API — templates, bulk sends, inbox, chatbots and sequences, just by asking. 30 days free, no card.
Start freeMore guides
How to handle WhatsApp STOP and opt-outs in your app
A customer replied STOP on WhatsApp. What must your app do? Honour the opt-out everywhere, block the next send, log it, and let people opt back in, with a tested webhook handler and the exact error to expect.
WhatsApp Cloud API webhook not working? A step-by-step checklist
Meta's WhatsApp webhook won't verify, or verifies but sends nothing? Work through six checks in order (verify token, public HTTPS, subscribed field, overrides, signature, 200 reply) with a tested Node receiver and curl commands.
Send a WhatsApp message with cURL: copy-paste commands
Send a WhatsApp template message from the command line with cURL. Check your key, send with a test key first, retry without double-sending, read the status, and a short shell script that handles the errors.
WhatsApp template variables: how to fill the parameters from the API (and why a send says missing_variables)
How to fill {{1}}, {{2}} and {{3}} in a WhatsApp template from code, with curl and Node examples, a check that counts the values before you send, and what the 132000 and 132012 errors mean when a send does reach Meta.