> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp Error Codes
> Diagnose and resolve every WhatsApp delivery, template, and account error you can hit through Zavu
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:
```json theme={null}
{
"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](/guides/receiving-messages/webhooks).
## Quick Triage
Use this decision tree before diving into the tables:
```mermaid theme={null}
flowchart TD
A[Message failed] --> B{Error category}
B -->|auth / integrity| C[Stop sending
Fix account first]
B -->|rate_limit| D[Back off,
retry with delay]
B -->|template| E[Fix template,
resubmit]
B -->|delivery| F[Check 24h window
or contact validity]
B -->|media| G[Re-encode or
resend asset]
B -->|flow| H[Edit flow JSON
or republish]
B -->|other| I[Inspect message,
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.
| 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](/guides/whatsapp/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](#c-integrity-errors) 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](/guides/broadcasts/overview) 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
```typescript theme={null}
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](/guides/sending-messages/smart-routing). |
| `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](/guides/whatsapp/templates/sending#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](/guides/whatsapp/templates/sending). |
| `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](/guides/whatsapp/templates/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](#g-whatsapp-flows-errors). |
| `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](/guides/sending-messages/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](/guides/whatsapp/overview#message-types)). |
### Detect the 24-hour window
```typescript theme={null}
const contact = await zavu.contacts.get({ 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](/guides/whatsapp/messages/image) 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](#c-integrity-errors) 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](/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](https://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](/guides/whatsapp/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:
```typescript theme={null}
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";
}
zavu.webhooks.on("message.failed", async (event) => {
const action = classify(event.data.errorCode);
switch (action) {
case "retry":
await enqueueRetry(event.data.id, { 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;
}
});
```
## Prevention Checklist
Verify phone format (E.164), template params, and 24h window state on your side.
A drop from `high` to `medium` is your first warning. Pause marketing before the platform does it for you.
Let Zavu fall back to SMS/email automatically when WhatsApp returns delivery errors.
`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](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/) — official reference
* [Business messaging policy](https://www.whatsapp.com/legal/business-policy/) — content rules behind integrity and template rejections
* [Messaging limits](https://developers.facebook.com/docs/whatsapp/cloud-api/overview#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](https://github.com/zavudev) so we can add it.
## Next Steps
Automatic channel fallback when WhatsApp delivery fails
Avoid 132xxx errors by getting templates right the first time
React to failures in real time
How Zavu paces sends to stay under WABA limits