WhatsApp Error Codes

When a WhatsApp message fails, Zavu surfaces the upstream error code in the message's errorCode and errorMessage fields, plus on the message.failed webhook. This page maps every error you can hit, explains why it happens, and tells you the exact action to take — in code, in the dashboard, or with your end user.

How Zavu Returns Errors

Every failed WhatsApp message exposes the same shape, whether you read it from the API, the dashboard, or a webhook:

JSONCopy
{
  "id": "msg_01HX...",
  "status": "failed",
  "channel": "whatsapp",
  "errorCode": "131047",
  "errorMessage": "WhatsApp: 24-hour window closed — this contact has not messaged you in the last 24 hours, so free-form messages are refused. Send an approved template to open the conversation."
}

• errorCode — Meta's code, as a string (see tables below). Number(errorCode) is safe, and is what the switch further down does.
• errorMessage — a sentence for a human. For a few codes Zavu replaces Meta's own wording, which points the reader at the wrong problem; the code never changes, so branch on errorCode and display errorMessage.

Quick Triage

Use this decision tree before diving into the tables:

flowchart TD
    A[Message failed] --> B{Error category}
    B -->|auth / integrity| C[Stop sending<br/>Fix account first]
    B -->|rate_limit| D[Back off,<br/>retry with delay]
    B -->|template| E[Fix template,<br/>resubmit]
    B -->|delivery| F[Check 24h window<br/>or contact validity]
    B -->|media| G[Re-encode or<br/>resend asset]
    B -->|flow| H[Edit flow JSON<br/>or republish]
    B -->|other| I[Inspect message,<br/>retry if transient]

A. Authorization Errors

These mean your WhatsApp Business Account (WABA) or the underlying app credentials aren't valid for the action you tried. They almost never resolve by retrying — you must reconnect the account.

B. Rate Limit & Throttling Errors

WhatsApp enforces several independent limits: per-app calls, per-WABA throughput, per-recipient pacing, and account-level spam protection. Each has a different remediation window.

Retry strategy

TypeScriptCopy
async function sendWithBackoff(payload, attempt = 0) {
  try {
    return await zavu.messages.send(payload);
  } catch (err) {
    const retriableCodes = [4, 80007, 130429];
    if (retriableCodes.includes(Number(err.errorCode)) && attempt < 5) {
      const delay = Math.min(60_000, 1000 * 2 ** attempt);
      await new Promise((r) => setTimeout(r, delay));
      return sendWithBackoff(payload, attempt + 1);
    }
    throw err;
  }
}

C. Integrity Errors

Account-level enforcement actions. The message wasn't sent because the platform restricted the sender or recipient.

D. Template Errors

Triggered when sending a template message. Most are fixable by editing the template; a few require creating a new one.

E. Delivery Errors

The template/account was fine, but the message couldn't reach the recipient.

Detect the 24-hour window

TypeScriptCopy
const contact = await zavu.contacts.retrieve({ id: contactId });
const last = contact.whatsapp?.lastInboundAt;
const within24h = last && Date.now() - new Date(last).getTime() < 24 * 60 * 60 * 1000;

await zavu.messages.send({
  to: contact.phone,
  channel: "whatsapp",
  ...(within24h
    ? { text: "Quick update on your order…" }
    : { template: { name: "order_update", language: "en", variables: ["#1234"] } }),
});

F. Media Errors

Issues with the file attached to an inbound or outbound message.

G. WhatsApp Flows Errors

Errors specific to interactive Flows (multi-step forms inside WhatsApp).

H. Miscellaneous Errors

Codes that don't fit cleanly elsewhere but you'll see eventually.

Programmatic Error Handling

Treat errors by category, not by code, to keep your code resilient as new codes appear:

TypeScriptCopy
function classify(errorCode: number): "retry" | "fix-template" | "fix-account" | "fallback" | "drop" {
  if ([4, 80007, 130429, 131000, 131016, 131057].includes(errorCode)) return "retry";
  if (errorCode >= 132000 && errorCode <= 132099) return "fix-template";
  if ([0, 3, 10, 190, 368, 131005, 131031, 131037, 131042, 131045].includes(errorCode)) return "fix-account";
  if ([131026, 131047, 131049, 131051].includes(errorCode)) return "fallback";
  return "drop";
}

// Webhooks are plain HTTPS POSTs to the URL configured on your sender, so this
// lives in your own endpoint. Verify the signature first: see
// /guides/receiving-messages/security
app.post("/webhooks/zavu", async (req, res) => {
  const event = req.body;
  if (event.type !== "message.failed") return res.sendStatus(200);

  const action = classify(Number(event.data.errorCode));
  switch (action) {
    case "retry":
      await enqueueRetry(event.data.messageId, { delay: 60_000 });
      break;
    case "fallback":
      await sendViaSMS(event.data);
      break;
    case "fix-template":
    case "fix-account":
      await notifyOpsTeam(event.data);
      break;
    case "drop":
      await logForReview(event.data);
      break;
  }
  res.sendStatus(200);
});

Prevention Checklist

References

The error codes documented here are defined by the WhatsApp Business Platform. For the authoritative, always-up-to-date list maintained by Meta:

• Cloud API error codes — official reference
• Business messaging policy — content rules behind integrity and template rejections
• Messaging limits — throughput tiers and quality rating

This guide adapts those codes with Zavu-specific handling (error shape, webhooks, Smart Routing fallback). If Meta adds a new code that isn't listed here yet, Zavu still passes it through unchanged on errorCode — please open an issue so we can add it.

Next Steps