Complete WhatsApp Business API Error Codes List
A definitive technical directory of WhatsApp Cloud API error codes, Graph API HTTP statuses, webhook failure objects, root causes, and production-tested remediation steps.
WhatsApp Cloud API errors fall into two categories: synchronous HTTP errors and asynchronous webhook delivery failures. The most common error codes in production are: 131026 (undeliverable recipient phone), 131047 (24-hour conversation window closed; requires approved template), 130429 (throughput rate limit reached; requires exponential backoff), 132000 (template parameter mismatch), and 190 (expired system user access token).
How WhatsApp API Errors Are Structured
WhatsApp communicates errors through two primary mechanisms: synchronous HTTP responses and asynchronous webhook delivery receipts.
1. Synchronous HTTP Errors
Returned instantly in response to your POST request to the Graph API endpoint. Covers authorization failures (HTTP 401), invalid parameter formats (HTTP 400), rate limit spikes, or missing tokens.
2. Asynchronous Webhook Statuses
When an HTTP 200 OK confirms message acceptance, actual downstream delivery might still fail. WhatsApp sends a webhook status event with a nested errors array explaining why delivery failed.
3. Error Subcodes & Details
Meta uses granular 6-digit codes (e.g., 131047, 132000) accompanied by localized diagnostic messages to pinpoint the exact failure point in the conversational lifecycle.
Category 1: Message Delivery & Customer Session Failures
Errors triggered during recipient routing, session window expiry, or media transfer.
| Code | Title / Status | Root Cause | Engineering Resolution |
|---|---|---|---|
131026 |
Message Undeliverable | Recipient number not registered on WhatsApp, has blocked your number, has opted out, or network routing failed. | Flag number as inactive in your CRM. Do not retry repeatedly to protect Phone Quality Rating. |
131047 |
Re-engagement Message Failed | Attempted to send a free-form text/media message after the 24-hour customer service window expired. | Dispatch an approved Meta template message to prompt the user to re-open the 24-hour conversational window. |
131051 |
Unsupported Message Type | Attempted to send an unsupported message format or payload structure. | Verify that payload adheres to standard text, image, document, audio, video, sticker, or interactive format. |
131052 |
Media Download Failed | WhatsApp Cloud servers were unable to download media from the provided public URL. | Ensure the media URL is publicly accessible, SSL-valid, and returns appropriate Content-Type headers (e.g. image/jpeg). |
131053 |
Media File Size Too Large | The attached file exceeds WhatsApp maximum file size limits (e.g., images > 5MB, video > 16MB, documents > 100MB). | Compress media assets or host large collateral on external storage and send an interactive download link. |
Category 2: Template Structure & Parameter Mismatches
Errors caused by incorrect template names, variable counts, or paused template statuses.
| Code | Title / Status | Root Cause | Engineering Resolution |
|---|---|---|---|
132000 |
Parameter Count Mismatch | The number of variables provided in the API call does not match the placeholder count in the approved template. | Verify that your API payload provides parameters for all variables (e.g., {{1}}, {{2}}). |
132001 |
Template Does Not Exist | The specified template name does not exist, was rejected, or is not approved in the requested language code (e.g., en_US vs en_IN). |
Verify exact template name spelling and matching language code in WhatsApp Manager. |
132005 |
Hydrated Text Too Long | The populated template body exceeds WhatsApp’s 1024-character maximum limit after variable substitution. | Shorten parameter strings or trim dynamic text injections to remain within the 1024-character ceiling. |
132015 |
Template Paused / Disabled | The template was automatically paused by Meta due to low recipient quality ratings or high block rates. | Check WhatsApp Manager ➔ Message Templates. Edit template wording, improve targeting, and request unpausing. |
Category 3: Rate Limiting, Authentication & Account Status
Errors governing security tokens, throughput caps, and WABA account integrity.
| Code | Title / Status | Root Cause | Engineering Resolution |
|---|---|---|---|
130429 |
Cloud API Rate Limit Hit | You have exceeded the Cloud API throughput limit (messages per second) or reached your 24-hr tier cap. | Implement exponential backoff retry queues. Throttle campaign broadcasts across scheduled batches. |
190 |
Access Token Expired / Invalid | The System User Access Token has expired, was revoked, or lacks required permissions. | Generate a permanent System User Token in Meta Business Suite with whatsapp_business_messaging permissions. |
100 |
Invalid Parameter | Malformed JSON syntax, incorrect field names, or invalid recipient phone number format. | Validate payload against Meta Graph API specifications. Ensure phone numbers include country code without symbols (+). |
133010 |
Phone Number Not Registered | The phone number ID in the API URL has not completed two-factor registration with Cloud API. | Execute the registration endpoint (POST /v20.0/{phone_number_id}/register) with the 6-digit PIN. |
131042 |
Payment Account Required | Your WhatsApp Business Account has no active payment method or your credit card was declined. | Navigate to Meta Business Suite ➔ Payments and add a valid international payment method. |
131056 |
Policy Violation Restriction | The business has violated Meta Business or Commerce Policies, resulting in account suspension. | Submit a formal appeal ticket through Meta Business Support Home with compliance justification. |
Automated Error Mitigation with NY Digital CRM
Developers shouldn't have to spend weekends manually unblocking failed API calls. Under our ₹99,999/year enterprise plan, NY Digital's CRM incorporates production-grade reliability architecture.
Zero-Loss Resiliency Features
- Exponential Backoff Retries: Automatic multi-tier retries for transient
130429and 500 errors. - Dead-Letter Queue (DLQ): Isolates failed messages for inspection without halting broadcast queues.
- Permanent Token Management: Automated token health monitors eliminate
190authorization outages. - Pre-Flight Parameter Validation: Verifies parameter counts before API transmission to eliminate
132000errors.
Frequently Asked Questions
Quick answers to common developer and marketer questions.
Why do we receive HTTP 200 but the message never reaches the customer?+
HTTP 200 only confirms that Meta Cloud API has accepted your request into its queue. Downstream delivery failures (e.g., number turned off, invalid number, blocked sender) are reported asynchronously via your webhook URL.
How can we check our current messaging tier limit?+
In Meta Business Suite, navigate to WhatsApp Manager ➔ Account Tools ➔ Phone Numbers. The messaging limit column will display your current tier (Tier 1: 1K, Tier 2: 10K, Tier 3: 100K, or Unlimited).
What should we do if Meta rejects our payment card (error 131042)?+
Ensure that international transactions and e-mandates are enabled on your corporate credit card with your issuing bank. Alternatively, arrange for Meta monthly invoicing credit line through an authorized partner like NY Digital.
Can NY Digital integrate WhatsApp Cloud API with our existing CRM/ERP?+
Yes. We provide pre-built webhooks and REST endpoints to integrate with Salesforce, Zoho, LeadSquared, HubSpot, Shopify, or custom MySQL/PostgreSQL enterprise backends.