Everything looks fine. Your request is structured correctly, the endpoint works, the payload is valid. Then the response comes back with a number — 131049, 132015, 131026 — and a simple messaging workflow becomes a troubleshooting exercise.
WhatsApp API errors frustrate developers because the codes don’t always tell the full story. A campaign stops, automations break, notifications fail — and all you have is a code and a failed request. The good news: most WhatsApp API errors are highly predictable. Once you know what the codes mean and why they occur, troubleshooting gets much easier. Here are the most common ones, with causes and fixes, sourced from Meta’s Cloud API error reference.
Why WhatsApp Uses Error Codes
The WhatsApp Business Platform processes billions of messages, and error codes help you pinpoint where a request failed — templates, number quality, policy restrictions, rate limits, permissions, invalid parameters, customer behaviour, or account configuration. Identifying the category of failure usually gets you most of the way to a fix.
A 3-Question Framework
Before diving into individual codes, ask three questions:
- Did the request reach WhatsApp? If not, suspect authentication, endpoint config, or request formatting.
- Did WhatsApp accept the request? If not, suspect templates, parameters, permissions, or policy.
- Was it accepted but not delivered? If so, suspect customer availability, quality ratings, or delivery restrictions.
This framing narrows almost any error fast.
Error 131049: Healthy Ecosystem / Marketing Limit
What it means: Meta intentionally chose not to deliver the message to maintain “healthy ecosystem engagement.” In plain terms, the recipient hit their per-user marketing template message limit. (On-Premises returned the equivalent code 1026.)
Why it happens: WhatsApp caps how many marketing templates a user receives in a window, and the cap adapts to how much they engage. If several businesses have already messaged that user recently, a new marketing message can be blocked even on your first attempt.
How to fix it: Don’t retry immediately — that just repeats the error. Wait at least 24 hours and retry at gradually increasing intervals, and reduce marketing frequency to high-intent audiences. We cover this in depth in our frequency capping guide.
Error 132015: Template Paused
What it means: a message template has been paused — one of the most common template errors.
Why it happens: WhatsApp pauses templates that generate negative signals (blocks, reports, low engagement) to protect customer experience, usually due to irrelevant messaging, excessive promotion, poor targeting, or weak consent.
How to fix it: stop sending the paused template, review blocking/engagement trends and audience quality, improve relevance, then submit an improved template. Full playbook in our template pacing vs pausing guide.
Error 131026: Message Undeliverable
What it means: a broad “message undeliverable” signal.
Why it happens: the recipient isn’t reachable on WhatsApp — invalid number, the person isn’t a WhatsApp user, an outdated app, the user hasn’t accepted WhatsApp’s latest terms, or messaging conditions aren’t met.
How to fix it: verify number formatting (country code, validity), confirm the number is active on WhatsApp, and ensure your messaging practices align with platform requirements.
Error 131047: Re-Engagement Required
What it means: more than 24 hours have passed since the customer’s last message, so the customer service window has closed and you can’t send a free-form message.
How to fix it: send an approved template to re-open the conversation instead of a free-form message. Designing flows that keep the 24-hour window open (and using templates correctly outside it) avoids this entirely.
Authentication Errors
Auth errors (including AuthException, error code 0) usually mean an expired or invalid access token, incorrect authentication headers, or changed permissions.
Fix: refresh access tokens, validate configuration, and review permission settings. These are usually straightforward once identified — a common gotcha is using a temporary token instead of a permanent one.
Invalid Parameter Errors
These occur when a request contains missing fields, invalid parameters, incorrect payload structures, or unsupported formats.
Fix: review the request documentation, validate payload structure, verify required fields, and test carefully. Among the easiest errors to resolve.
Rate Limit Errors
Throughput limits trigger when you send extremely large volumes, exceed request thresholds, or scale traffic too aggressively.
Fix: retry intelligently with backoff, queue requests, scale gradually, and monitor throughput. Proper request management prevents most rate-limit issues — and ties into healthy scaling, as covered in our bulk message guide.
Permission Errors
Permission issues arise when an account lacks required access, a feature isn’t enabled, or configuration changed. Fix: review account configuration, verify access rights, and confirm platform settings. Make permissions a standard part of your troubleshooting workflow.
Quick Reference Table
Code | Meaning | First fix |
|---|---|---|
131049 | Per-user marketing limit (healthy ecosystem) | Don’t retry now; wait 24h+, reduce frequency |
132015 | Template paused (low quality) | Stop template; improve relevance; resubmit |
131026 | Message undeliverable | Verify number; check WhatsApp status |
131047 | Re-engagement required (window closed) | Send an approved template |
0 / Auth | Authentication failed | Refresh token; check permissions |
Rate limit | Throughput exceeded | Back off, queue, scale gradually |
Troubleshoot Systematically
- Identify the error code — it points to the category of issue.
- Determine the failure point — auth, validation, template, or delivery?
- Review recent changes — new templates, updated integrations, volume spikes, config edits.
- Validate inputs — phone numbers, payloads, parameters, authentication.
- Review messaging quality — customer feedback often explains delivery and template errors.
Many template errors are really customer-behaviour problems in disguise: messages people ignore, block, or report eventually create operational failures. Technical excellence alone doesn’t guarantee delivery — relevance matters just as much.
Conclusion
WhatsApp API error codes look intimidating, but most fall into a handful of predictable categories: authentication, parameter validation, delivery problems, template restrictions, quality limits, and policy issues. 131049 points to per-user marketing limits; 132015 means a paused template; 131026 is a broad undeliverable; 131047 means the 24-hour window closed.
The goal isn’t memorising every code — it’s building systems that quickly identify, diagnose, and resolve failures. At scale, reliable WhatsApp operations depend on observability and process as much as on sending messages.
FAQs
What do WhatsApp API error codes mean?
They identify specific failure categories — authentication, delivery, template restrictions, invalid parameters, rate limits, and policy limitations — so you can pinpoint and fix the cause quickly.
What is error 131049?
131049 means Meta chose not to deliver a marketing template because the recipient hit their per-user marketing message limit (“healthy ecosystem engagement”). Don’t retry immediately; wait and reduce frequency.
What is error 132015?
132015 means a template has been paused due to poor quality signals such as blocks, reports, or low engagement. Improve relevance and submit a revised template rather than resending.
What is error 131026?
131026 is a broad “message undeliverable” error — often an invalid number, a non-WhatsApp user, an outdated app, or unmet messaging conditions. Verify the number and WhatsApp status.
How can I prevent WhatsApp API errors?
Validate inputs before sending, implement logging, monitor delivery and quality metrics, maintain clean customer data, test changes gradually, and review template performance regularly.
