Blog
WhatsApp API Error Codes List: Troubleshooting & Fixes Guide
Want a Quick Summary?
Summarize this article instantly with ChatGPT.
When a WhatsApp Business API campaign stalls or a transactional notification fails to reach a customer, relying solely on HTTP status codes creates blind spots. Meta's Cloud API returns generic HTTP 400 or 500 status codes across dozens of completely different failures—and even more importantly, a synchronous POST /messages call often returns HTTP 200 OK before failing asynchronously seconds later inside your statuses webhook payload. Treating every failure identically such as blindly retrying a per-user marketing cap or a closed 24-hour window wastes API calls, triggers rate-limit blocks, and damages your phone number's Meta quality rating.
Resolving WhatsApp API error codes reliably requires parsing the exact numeric code and error_data.details fields from both synchronous JSON responses and asynchronous webhook events, then routing each error family to the right automated retry or human fix. Below is the complete 2026 engineering and operations reference covering every major WhatsApp Cloud API error code family, root causes, and immediate fixes.
1. How to Read a WhatsApp Cloud API Error Response
Every synchronous API error and asynchronous webhook failure surfaces a structured JSON object containing four critical diagnostic fields:
code(Numeric Error Identifier): The exact Meta Graph or WhatsApp Cloud API error code (such as190,130429,131047, or132001). Always branch your backend error-handling logic on this integer rather than matching human-readable text strings that may change.error_data.details(Root-Cause Explanation): Plain-language explanation naming the exact invalid parameter, expired token, or missing template variable.type(Error Classification): TypicallyOAuthExceptionacross most Graph API errors, even when the underlying issue involves rate limits or payload formatting.fbtrace_id(Meta Support Trace ID): Unique per-request log identifier required whenever escalating persistent platform bugs to Meta Developer Support alongside your timestamp and Phone Number ID.
2. Authentication, Permission & Account Integrity Error Codes
These errors indicate expired System User tokens, missing Graph API scopes, billing blocks, or policy restrictions on your WhatsApp Business Account (WABA):
| Error Code | Official Error Meaning | Common Root Cause | Immediate Resolution |
|---|---|---|---|
| 0 | Unable to authenticate app user | Access token invalidated or revoked after password or admin permission changes. | Generate a new permanent System User token in Meta Business Settings and redeploy. |
| 3 / 10 / 200–299 | Capability or permission issue | App lacks whatsapp_business_messaging or whatsapp_business_management scope, or public key is not allowlisted for Flows. |
Inspect scopes in Meta's Access Token Debugger and re-grant required permissions. |
| 190 | Access token expired or invalid | Temporary token expired or rotated out of sync. | Replace with a non-expiring System User token in your backend environment variables. |
| 200 | No access token provided | Missing Authorization: Bearer header on GET/POST API request. |
Attach a valid Bearer token header to every outbound Graph API call. |
| 368 | Account temporarily restricted or disabled | WhatsApp Business Account violated Meta Commerce or Business Messaging policies. | Open Meta Business Support Home, review the flagged policy notice, and submit an appeal. |
| 130497 | Country messaging restriction | WABA is restricted from messaging users in specific destination countries. | Verify allowed destination markets under Meta's Business Messaging Policy for your vertical. |
| 131042 | Business eligibility payment issue | Missing, expired, or declined credit line / payment method in Meta Business Manager. | Attach a valid payment method or resolve overdue invoices in Meta Billing settings. |
3. Rate-Limit, Throttling & Quality Protection Error Codes
When your system exceeds throughput ceilings or sends messages that trigger user blocks and frequency caps, Meta enforces protective error codes:
| Error Code | Official Error Meaning | Common Root Cause | Immediate Resolution |
|---|---|---|---|
| 4 / 80007 | App or Account API call rate limit reached | Too many Graph API requests per hour (such as excessive template syncs or status polling). | Implement exponential backoff with jitter, cache metadata, and batch non-critical calls. |
| 130429 | Cloud API message throughput limit hit | Sending messages per second (MPS) faster than your phone number's current throughput tier allows. | Queue outbound sends with rate pacing and retry failed bursts using exponential backoff. |
| 131048 | Spam / quality rate limit hit | Recent campaign triggered high user block or spam-report rates, dropping quality status. | Pause outbound broadcasts immediately, remove cold contacts, and verify explicit opt-ins. |
| 131049 | Per-user marketing template limit reached | Meta's ecosystem frequency cap blocked a Marketing template because the user already received too many promotional messages across brands. | Do not auto-retry immediately. Log separately from bad numbers and wait at least 24–48 hours or re-engage via a different channel. |
| 131056 | Pair rate limit (same sender-recipient) | Too many messages sent to the exact same user phone number within a short window. | Consolidate multi-bubble notifications into one structured message and add per-user cooldown timers. |
4. Messaging Window, Recipient & Payload Error Codes
These errors typically surface either synchronously on invalid payloads or asynchronously inside webhook delivery status callbacks:
| Error Code | Official Error Meaning | Common Root Cause | Immediate Resolution |
|---|---|---|---|
| 100 / 131008 | Invalid or missing required parameter | Misspelled JSON field or missing messaging_product, to, type, or language object. |
Validate request schema against Meta's current Cloud API endpoint specification. |
| 131009 | Parameter value not valid | Malformed E.164 recipient number, unsupported media MIME type, or expired media URL. | Format numbers cleanly with country code (no spaces/symbols) and verify media size/format. |
| 131021 | Recipient cannot be the sender | Test script sent a message where the to field matched your own business phone number. |
Replace the to field with an external test mobile number. |
| 131026 | Message undeliverable / recipient unreachable | Target number is not registered on WhatsApp, uses an outdated app version, or has not accepted Meta's latest Terms of Service. | Suppress repeated sends to invalid numbers and verify opt-in number accuracy. |
| 131047 | Re-engagement message required | More than 24 hours elapsed since the customer's last inbound message, blocking free-form text/media replies. | Initiate the conversation using a pre-approved Meta Message Template instead of free-form text. |
| 131050 | User opted out of marketing messages | Recipient previously tapped Stop/Unsubscribe or blocked marketing promotions from your business. | Immediately mark the contact as unsubscribed in your CRM and halt all Marketing templates. |
| 131051 | Unsupported message type | Payload used a deprecated or unsupported interactive/media object structure. | Switch to an officially supported Cloud API message type (text, media, interactive, template, or Flow). |
5. Template Creation & Template Delivery Error Codes
Template errors occur either when submitting templates via the Graph API or when runtime variables fail to match an approved template structure:
| Error Code | Official Error Meaning | Common Root Cause | Immediate Resolution |
|---|---|---|---|
| 132000 | Template parameter count mismatch | Number of dynamic variables passed in the API payload does not match placeholders ({{1}}, {{2}}) in the approved template. |
Ensure your runtime parameters array supplies an exact, non-null value for every placeholder. |
| 132001 | Template does not exist or is not approved | Typo in template.name, mismatched language.code (e.g., en vs. en_US), or status is still Pending. |
Verify exact template name, locale code, and Active - Approved status in WhatsApp Manager. |
| 132007 / 132015 | Template violated policy or paused due to low quality | High negative user feedback caused Meta to pause or disable the template. | Revise copy/targeting, tighten opt-in segmentation, or submit a clearer replacement template. |
| 2388040 | Template character limit exceeded | Header, body, footer, or button text exceeded Meta's character cap during template creation. | Trim copy within official limits (e.g., 1,024 chars for body, 60 chars for header/footer, 25 chars for buttons). |
| 2388293 / 2388299 | Variable-to-word ratio or leading/trailing variable error | Template starts or ends directly with a {{1}} variable, or has too many placeholders relative to static text. |
Add static context words before and after variables and expand descriptive body copy. |
4 Engineering Rules for Resilient WhatsApp Error Handling
Building these four guardrails into your messaging queue prevents runaway retries and keeps delivery rates high:
- Classify Errors Into Retryable vs. Non-Retryable Queues: Only auto-retry transient server or throughput errors (
1,2,4,80007,130429,131016) using exponential backoff with jitter. Never auto-retry policy, window, or frequency-cap codes (368,131047,131049,131050,132001). - Monitor Webhook
statusesFailures Separately From HTTP Responses: Because errors like131026,131047, and131049arrive asynchronously via webhooks after an initial HTTP200response, ingest all webhook error arrays into your observability alerts. - Alert Engineering vs. Marketing on Code Spikes: Route spikes in
190(expired token) or132000(variable mismatch) directly to engineering on-call, while routing spikes in131048or132015(quality degradation) to growth teams to pause campaigns immediately. - Trigger SMS Fallback Only on High-Priority Utility Failures: When a critical OTP or out-for-delivery alert returns
131026(recipient offline/unreachable), route that specific message to a transactional SMS fallback without clogging your WhatsApp retry queue.
Keeping Your WhatsApp API Pipeline Fast and Reliable
Mastering WhatsApp API error codes eliminates silent message drops and protects your business number from sudden rate limits. By parsing numeric error codes across both synchronous API responses and asynchronous status webhooks, separating transient throttling from permanent opt-out or template mismatches, and enforcing strict variable validation before dispatch, engineering and marketing teams keep critical customer conversations running smoothly at scale.
Looking for Measurable Business Growth?
Partner with BrandStory for end-to-end digital & creative excellence.
Transform Your Digital Growth with BrandStory
From SEO, PPC, social media marketing, and content marketing to website development, branding, and lead generation, BrandStory delivers result-driven digital marketing services in Dubai and across the UAE, helping businesses attract, engage, and convert more customers.
Trusted by 1000+ leading brands in Dubai and globally including:
Related Blogs
TikTok Ads to WhatsApp: Instant Messaging Ads Setup, ROAS & API Rules
Performance marketers running vertical 9:16 video ads on TikTok across retail, real estate, aesthetics, automotive, and ...
WhatsApp Ad Welcome Message: Click-to-WhatsApp Scripts, Icebreakers & Rules
Paid social teams running Click-to-WhatsApp ads on Meta or Instant Messaging ads on TikTok routinely lose 40% to 60% of ...
Click-to-WhatsApp Ads Vs. Lead Forms: CPL in AED, Quality & ROAS
Performance marketers running Meta campaigns across real estate, aesthetic clinics, automotive showrooms, education, and...
WhatsApp Broadcast Vs. Group: Privacy, Limits, Business API & Use-Cases
When small business owners, community managers, and marketing teams start messaging multiple customers on WhatsApp, they...
WhatsApp Business Messaging Policy: Opt-In Rules, Template Tiers & Quality Guide
Scaling outbound campaigns on the WhatsApp Business Platform without strict policy governance is the fastest way to get ...
WhatsApp Link With Message: Official Syntax, URL Encoding & Examples
Forcing website visitors, Instagram profile browsers, or QR-code scanners to manually save a phone number before startin...
