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_mismatch on 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_limited and 5xx, with backoff and a cap.
  • Never retry 422, 402 or 4xx rules in a loop.
  • Track real delivery with message.status, not the 202.
  • 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 with Retry-After) and app/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 free