WhatsApp Cloud API Error Codes: Meanings and How to Fix Them

This guide is for developers and messaging operations teams who see failed WhatsApp messages and need to know, quickly, whether to fix the request, wait, change the message type or stop. Every code below was checked against Meta's Cloud API error code reference; codes and wording change, so confirm against that page before hard-coding logic.

Where do WhatsApp Cloud API errors appear?

Errors appear in two places, and you need to capture both. Request errors come back immediately in the API response; delivery errors arrive later in a status webhook.

• Synchronous errors. The send request is rejected and the response contains an error object with code, message, type and often error_data.details. Typical examples are expired tokens, missing parameters and template mismatches.
• Asynchronous errors. The send request succeeds and returns a message ID, but a later webhook reports status: failed with an errors array. Typical examples are closed service windows, undeliverable recipients and marketing limits.

A common mistake is logging only the HTTP response. Teams then believe a campaign succeeded because every request returned a message ID, while hundreds of messages failed in webhooks. For how statuses relate to each other, see sent, delivered, read and failed explained.

What are the most common WhatsApp error codes?

The table lists the codes most teams encounter, grouped by what you should do next. Descriptions paraphrase Meta's reference.

How do you fix the errors that cause most failed campaigns?

In practice, a handful of codes cause most failures. Each has a clear decision rule.

131047: the service window is closed

The customer last messaged more than 24 hours ago. Free-form text, media and interactive messages are allowed only inside the 24-hour customer service window; outside it you must use an approved template; see the 24-hour customer service window. Agents often hit this when replying to an old chat. Show agents the window status and offer a template picker when it has expired.

131026: message undeliverable

Start with number hygiene: international format, correct country code, no leading zero after the code. Then accept that some numbers are simply not on WhatsApp, or are on an old app version. For time-critical messages such as OTPs, fall back to SMS. See WhatsApp vs SMS vs RCS.

131049 and 131050: marketing limits and opt-outs

Both affect marketing messages. 131050 is the user's explicit choice to stop marketing; suppress them for marketing and subscribe to Meta's user preferences webhook. 131049 means Meta chose not to deliver to protect user engagement; Meta advises waiting at least 24 hours, and sooner retries are likely to fail again. Reduce frequency and improve relevance rather than resending.

130429, 131048 and 131056: sending too fast or too much

130429 is throughput: queue messages and apply backoff. 131056 is pair-level: you are messaging one person too often. 131048 is a quality signal on the sender number and needs a content and targeting fix, not a retry. See messaging limits and quality rating.

132000, 132001 and 132012: template mismatches

These are almost always integration bugs. The template name, language code (for example ar versus en_US) and number of variables must match exactly what was approved. Build a test that sends each template with sample values whenever you edit it.

A retry policy you can implement

Use this checklist to classify each failure automatically.

1. Log the code, title, error_data.details, message ID, recipient and template name.
2. Never retry 131050, 131021, 132016, 368 and 131031. Flag 368 and 131031 to an administrator immediately.
3. Fix then retry authorization (0, 190, 10), parameter (131008, 131009, 135000), template (132000 to 132015) and billing (131042) errors. Alert the owning team.
4. Back off and retry 130429, 4, 80007, 131016 and 131057 using exponential backoff with a cap.
5. Change channel or message type for 131047 (template) and 131026 (SMS or email).
6. Wait 24 hours or more for 131049 and review campaign frequency.
7. Report failures by code in campaign reports, not as a single "failed" total.

Worked example: a Riyadh retailer's failed promotion

A synthetic example. "Najd Home" sends a marketing template to 20,000 opted-in customers. The API accepts every request, but the status webhooks show around 1,400 failures.

Grouped by code, the picture is clear. The largest group is 131049, so the team removes those users from the next two sends and lowers weekly frequency. A smaller group is 131026; analysis shows many numbers stored with a local leading zero, which a normalization fix resolves. Several 131050 users are suppressed for marketing permanently. A few 130429 errors came from the opening burst, so sending is now paced through a queue.

Common mistakes and honest limits

• Treating every failure as retryable. It wastes spend and can lower quality.
• Hard-coding Meta's text. Meta updates titles and descriptions; key logic on the numeric code and keep a lookup table you can update.
• Ignoring error_data.details. It often names the exact faulty parameter.
• Not every failure has a fix. Some recipients cannot be reached on WhatsApp, and Meta does not explain every 131049 decision. Plan an alternative channel.

How OmniChannels.ai helps

OmniChannels.ai, powered by BroadNet Technologies, gives teams delivery reports in summary and advanced views, with filters and CSV export, so failed messages can be analysed by campaign. Channel fallback can resend through RCS or SMS when WhatsApp fails, and templates are previewed on a phone mock-up and tracked through approval, reducing mismatch errors. Webhooks report FAILED and REJECTED statuses in one normalised format, and the public developer docs include an errors and limits reference.