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.

All error codes on this page are the canonical codes returned by the WhatsApp Business Platform. Zavu passes them through unchanged so you can keep your existing handlers if you migrate from another stack.

How Zavu Returns Errors

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

{
  "id": "msg_01HX...",
  "status": "failed",
  "channel": "whatsapp",
  "errorCode": 131047,
  "errorMessage": "Re-engagement message",
  "errorCategory": "delivery",
  "retriable": false
}

errorCode — numeric code (see tables below)
errorCategory — one of auth, rate_limit, integrity, template, delivery, media, flow, other
retriable — whether retrying the same payload could succeed without changes

Subscribe to the message.failed event on your webhook to react in real time instead of polling. See Webhooks.

Quick Triage

Use this decision tree before diving into the tables:

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.

Code	Name	Why it happens	What to do
`0`	AuthException	The platform can’t authenticate the app behind the sender.	Reconnect the WhatsApp sender from Senders → Connect WhatsApp. See Connect WhatsApp.
`3`	API Method	The endpoint exists but the calling app lacks the right scopes.	Reconnect with the full permission set; do not edit scopes manually.
`10`	Permission Denied	The phone number isn’t registered to your WABA, or messaging permission was revoked.	Verify the number appears under your sender and is in `connected` state.
`190`	Access Token Expired	The long-lived token rotated or was invalidated.	Reconnect the sender — Zavu will rotate the token automatically.
`200–299`	Permission Errors	A specific capability (templates, media, flows) was disabled.	Check the WABA status in the dashboard; if blocked, follow the Integrity flow.

If you see auth errors on every message, treat it as an outage on that sender. Pause broadcasts until the sender is connected again to avoid burning quality rating.

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.

Code	Name	What it actually limits	What to do
`4`	Too Many Calls	App-level API call rate	Back off with exponential delay (start 1s, cap 60s).
`80007`	Rate Limit Reached	Sender-level send rate	Retry after the `Retry-After` hint Zavu returns.
`130429`	Throughput Limit	Messages per second on the WABA	Spread sends; rely on Zavu’s Broadcasts for automatic pacing.
`131048`	Spam Rate Limit	Volume flagged as spammy by quality signals	Stop the campaign, inspect template quality, only resume once rating recovers.
`131056`	Pair Rate Limit	Too many messages to the same recipient	Hold sends to that contact for ~30 min. Other recipients are unaffected.
`133016`	Registration Limit	10 phone register/deregister attempts in 72h	Wait out the 72h window. Don’t script repeated reconnects.

Zavu Broadcasts automatically respect WABA throughput limits. If you’re hitting 130429 from your own send loop, switch to broadcasts.

Retry strategy

async function sendWithBackoff(payload, attempt = 0) {
  try {
    return await zavu.messages.send(payload);
  } catch (err) {
    const retriableCodes = [4, 80007, 130429];
    if (retriableCodes.includes(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.

Code	Name	Why it happens	What to do
`368`	Temporarily Blocked	A policy violation triggered a soft block on the WABA.	Open the WhatsApp Manager link in your sender details, resolve the flagged item, wait for unblock.
`130497`	Country Restriction	The destination country has messaging restrictions for your business.	Use a different channel for that country. See Sending Messages → SMS fallback.
`131031`	Account Locked	Disabled for repeated policy or commerce-policy violations.	Contact Zavu support — recovery requires an appeal.

Don’t keep retrying integrity errors. Each rejected send weighs against your quality rating.

D. Template Errors

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

Code	Name	Cause	Fix
`100`	Invalid Parameter	The variable keys don’t match the template’s parameter format — e.g. a named template (`{{customer_name}}`) was sent positional keys, or a required variable (including a text-header variable) was omitted.	Pass values keyed to match the template body, and include every variable. See How Variables Work.
`132000`	Parameter Count Mismatch	You passed fewer/more variables than the template defines.	Match `{{1}}, {{2}}, …` exactly. Inspect the template in the dashboard for the canonical count.
`132001`	Template Doesn’t Exist	Wrong name, wrong language, or template not approved.	Confirm `name` + `language` match an `approved` template. See Sending Templates.
`132005`	Translation Too Long	A localized version exceeds the character cap.	Shorten the body or header for that locale.
`132007`	Format Policy Violation	Disallowed formatting, unsafe characters, or banned content.	Edit the template, resubmit. See Template Approval.
`132012`	Parameter Format Mismatch	A variable type doesn’t match (e.g. text in a URL slot).	Send the correct type for each component.
`132015`	Template Paused	Quality rating dropped to “low” — sending is paused.	Edit the template content to improve clarity and resubmit.
`132016`	Template Disabled	Paused too many times; the template is permanently disabled.	Create a new template with improved copy.
`132068`	Flow Blocked	The attached Flow violates policy.	Review the Flow, fix, republish. See Flows.
`132069`	Flow Throttled	More than 10 flow messages sent within an hour.	Pace flow sends; investigate why the same flow triggers repeatedly.

A template that fails with 132015 or 132016 is a quality problem, not a code problem. Look at the template’s quality rating in Senders → Templates before editing blindly.

E. Delivery Errors

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

Code	Name	What happened	Recommended action
`131026`	Message Undeliverable	Recipient doesn’t have WhatsApp, hasn’t accepted ToS, or is on an outdated client version.	Fall back to SMS or email — Zavu’s Smart Routing can do this automatically.
`131047`	Re-engagement Required	More than 24h since the user last messaged you (no open session).	Send an approved template instead of a session message.
`131049`	Per-User Marketing Limit	The platform throttled a marketing message to protect the recipient.	Reduce marketing frequency to that contact. Transactional/utility templates are unaffected.
`131051`	Unsupported Message Type	The combination of message type and recipient device isn’t supported.	Use a supported type (see Message Types).
`131062`	Recipient Requires Phone Number	The message was sent to a BSUID but the type requires a phone number (one-tap, zero-tap and copy-code authentication templates).	Send authentication templates to the contact’s phone number. Recover it with a contact info request if you only have the BSUID.

Detect the 24-hour window

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.

Code	Name	Cause	Fix
`131052`	Media Download Error	Zavu couldn’t fetch the media the user sent.	Ask the user to resend, or request the file via another channel.
`131053`	Media Upload Error	Outbound media is wrong format, too large, or corrupted.	Verify against the media specs for that message type.

Common gotchas: PNGs over 5MB, MP4s without h264 video + aac audio, and stickers that aren’t 512×512 WebP.

G. WhatsApp Flows Errors

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

Code	Name	Cause	Fix
`100`	Flow Management Error	Duplicate flow name, invalid ID/JSON, or unreachable endpoint URL.	Validate flow JSON locally; ensure your endpoint returns 200 to the health check.
`139000`	Blocked by Integrity	The WABA can’t publish flows right now.	Resolve any Integrity issues first.
`139001`	Cannot Update Published Flow	Published flows are immutable.	Clone the flow, edit, publish a new version, deprecate the old one.
`139002`	Incomplete Flow Details	Required fields, validation data, or endpoint missing.	Complete every required field before publishing.
`139003`	Deprecation Error	Flow wasn’t published or is already deprecated.	Check current status before calling deprecate.
`139004`	Cannot Delete Published Flow	Published flows can’t be deleted.	Deprecate instead.
`139006`	Not Enough Metrics Data	Too few sessions to compute metrics.	Wait for more usage before requesting analytics.

H. Miscellaneous Errors

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

Code	Name	Cause	Fix
`131000`	Unknown Error	Unidentified upstream failure.	Retry once. If it persists, contact support with the message `id`.
`131005`	Access Denied	Permission revoked between messages.	Reconnect the sender.
`131008`	Missing Required Parameter	A required field is missing from the payload.	Check the API reference for that endpoint.
`131009`	Invalid Parameter Value	A value is outside the supported set.	Validate enums and lengths before sending.
`131016`	Service Unavailable	Temporary upstream outage.	Retry with backoff; check status.zavu.dev.
`131021`	Sender Equals Recipient	The sender phone number matches the recipient.	Swap one of them — you can’t message yourself.
`131037`	Missing Display Name	The sender has no approved display name.	Set and approve a display name in Senders → Profile. See Profile.
`131042`	Payment Issue	Billing block on the WABA.	Update payment details in Settings → Billing.
`131045`	Incorrect Certificate	Phone registration is in a bad state.	Reconnect the number from the dashboard.
`131057`	Account in Maintenance	Temporary platform-side maintenance.	Wait and retry; this clears on its own.

Programmatic Error Handling

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

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

Validate before send

Verify phone format (E.164), template params, and 24h window state on your side.

Watch quality rating

A drop from high to medium is your first warning. Pause marketing before the platform does it for you.

Use Smart Routing

Let Zavu fall back to SMS/email automatically when WhatsApp returns delivery errors.

Subscribe to webhooks

message.failed and template.status_changed catch problems before users do.

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

Smart Routing

Automatic channel fallback when WhatsApp delivery fails

Template Approval

Avoid 132xxx errors by getting templates right the first time

Webhooks

React to failures in real time

Rate Limiting

How Zavu paces sends to stay under WABA limits

Getting Started

Build agents

Send & receive

Operate

Developer tools

Integrations

WhatsApp Error Codes

How Zavu Returns Errors

Quick Triage

A. Authorization Errors

B. Rate Limit & Throttling Errors

Retry strategy

C. Integrity Errors

D. Template Errors

E. Delivery Errors

Detect the 24-hour window

F. Media Errors

G. WhatsApp Flows Errors

H. Miscellaneous Errors

Programmatic Error Handling

Prevention Checklist

Validate before send

Watch quality rating

Use Smart Routing

Subscribe to webhooks

References

Next Steps

Smart Routing

Template Approval

Webhooks

Rate Limiting

​How Zavu Returns Errors

​Quick Triage

​A. Authorization Errors

​B. Rate Limit & Throttling Errors

​Retry strategy

​C. Integrity Errors

​D. Template Errors

​E. Delivery Errors

​Detect the 24-hour window

​F. Media Errors

​G. WhatsApp Flows Errors

​H. Miscellaneous Errors

​Programmatic Error Handling

​Prevention Checklist

Validate before send

Watch quality rating

Use Smart Routing

Subscribe to webhooks

​References

​Next Steps

Smart Routing

Template Approval

Webhooks

Rate Limiting

How Zavu Returns Errors

Quick Triage

A. Authorization Errors

B. Rate Limit & Throttling Errors

Retry strategy

C. Integrity Errors

D. Template Errors

E. Delivery Errors

Detect the 24-hour window

F. Media Errors

G. WhatsApp Flows Errors

H. Miscellaneous Errors

Programmatic Error Handling

Prevention Checklist

References

Next Steps