Blog

WhatsApp API Error Codes List: Troubleshooting & Fixes Guide

by Madhavan A • Published: November 21, 2026
WhatsApp API Error Codes List: Troubleshooting & Fixes Guide
Contents
Want a Quick Summary?

Summarize this article instantly with ChatGPT.

Summarize with AI

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 as 190, 130429, 131047, or 132001). 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): Typically OAuthException across 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:

  1. 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).
  2. Monitor Webhook statuses Failures Separately From HTTP Responses: Because errors like 131026, 131047, and 131049 arrive asynchronously via webhooks after an initial HTTP 200 response, ingest all webhook error arrays into your observability alerts.
  3. Alert Engineering vs. Marketing on Code Spikes: Route spikes in 190 (expired token) or 132000 (variable mismatch) directly to engineering on-call, while routing spikes in 131048 or 132015 (quality degradation) to growth teams to pause campaigns immediately.
  4. 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.

Performance Driven

Looking for Measurable Business Growth?

Partner with BrandStory for end-to-end digital & creative excellence.

Talk to Our Experts
Data-driven ROI solutions
Madhavan A

Madhavan A

Madhavan A is a digital marketing expert with a strong SEO specialisation, bringing 8+ years of hands-on experience in driving organic growth and search visibility. He focuses on building data-driven strategies, optimising content performance, and delivering measurable results across competitive digital landscapes.

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:

Client Logo
Client Logo
Client Logo
Client Logo

Related Blogs

TikTok Ads to WhatsApp: Instant Messaging Ads Setup, ROAS & API Rules
November 21, 2026
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
November 21, 2026
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
November 21, 2026
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
November 21, 2026
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
November 21, 2026
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
November 21, 2026
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...