WhatsApp API error codes explained

When a WhatsApp message fails, Meta doesn’t just say “failed”. It sends a number, and that number tells you what went wrong and what to do next. This reference explains the error codes you’re most likely to meet on the WhatsApp Business Platform, grouped by what caused them, with a clear answer for each: retry it, fix something first, or stop.

All codes and descriptions come from Meta’s WhatsApp error codes reference (updated 18 June 2026). The explanations and fixes are ours, based on how these errors show up for ChatMitra customers.

How to read a WhatsApp API error

Errors reach you in one of two ways, and sometimes both:

• Synchronously, in the API response. Your send request is rejected straight away, for example because a parameter is missing or your token has expired. Nothing was sent.
• Asynchronously, in a webhook. Meta accepted the message (you got a message ID back), but it failed later. You receive a status update with "status": "failed" and an errors array. Delivery problems such as 131026 and 131049 arrive this way.

Meta recommends watching both the API response and the messages webhook for this reason. If you only check the response, every asynchronous failure looks like a success. Our guide to webhooks and message status explains the status flow.

An error in the API response looks like this:

{
  "error": {
    "message": "(#130429) Rate limit hit",
    "type": "OAuthException",
    "code": 130429,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "Cloud API message throughput has been reached."
    },
    "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

What each part is for:

Two points from Meta’s documentation are easy to miss. Meta says to build error handling around code and details, not HTTP status codes or subcodes. And the titles inside message “will eventually be deprecated”, so code that matches on the text “Rate limit hit” will break one day.

The most common WhatsApp API error codes

If you only read one table, read this one. The Retry? column shows what to do with the failed message:

The sections below explain each group in more detail, with the less common codes included.

Delivery errors

These errors mean Meta accepted your request but couldn’t, or wouldn’t, deliver the message to that person. They almost always arrive in the status webhook.

131026: message undeliverable

Meta lists three possible reasons:

• the number isn’t a WhatsApp number;
• the person hasn’t accepted WhatsApp’s latest Terms of Service and Privacy Policy;
• their WhatsApp is older than the minimum versions: Android and the Business app for Android 2.21.15.15, iPhone and the Business app for iPhone 2.21.170.4, KaiOS 2.2130.10, Web 2.2132.6.

Fix: first rule out your own mistakes. Is the number in full international format, with the country code and without a leading zero? Is it the customer’s WhatsApp number rather than a landline? If it is, contact them another way (SMS, email, a call) and ask them to open WhatsApp, accept any pending terms and update the app. Retrying the same message unchanged won’t help.

131026 is also what you’ll see for numbers that simply don’t use WhatsApp, so a high 131026 rate on a campaign usually points to an old or badly collected contact list.

131047: the 24-hour window has closed

“More than 24 hours have passed since the recipient last replied to the sender number.” Free-form messages, including text, media, reply buttons, lists and CTA URL buttons, can only be sent while a customer service window is open. The window opens or refreshes each time the customer messages or calls you, and lasts 24 hours. After that, Meta allows only approved template messages.

Fix: send the same information as an approved template. For an order update, that’s a utility template. If the customer replies, the window opens again and you can continue freely. Our guide to sending template messages covers the steps.

131049: not delivered to maintain healthy engagement

Meta’s details text reads: “This message was not delivered to maintain healthy ecosystem engagement.” In practice this is Meta’s per-user limit on marketing templates: a person who has recently received several marketing messages from businesses may not get yours.

Fix: don’t resend immediately. Meta’s advice is to wait at least 24 hours, noting that the limit “may be in effect for differing periods of time”, so an early retry just produces another 131049. Over time, send fewer and better-targeted marketing messages. Our marketing message errors guide explains frequency capping in more depth.

131050: the user stopped marketing messages

“This recipient has chosen to stop receiving marketing messages on WhatsApp from your business.” The customer used WhatsApp’s own option to stop offers from you.

Fix: don’t retry. Meta is explicit: the messages “will not be received”. Mark the contact as opted out of marketing in your CRM, and keep sending them utility messages they need, such as order updates, if they’re genuinely transactional. Meta’s user_preferences webhook tells you when someone stops or resumes marketing messages. For consent basics, see our WhatsApp opt-in guide.

Other delivery codes

Template errors

Template errors come in two kinds: errors when you send a template, and errors when you create or edit one.

132000: wrong number of variables

The number of values in your request doesn’t match the number of variables ({{1}}, {{2}}, …) in the template. This usually happens after someone edits a template and adds a variable, while the campaign, automation or code that sends it still passes the old number.

Fix: send exactly one value for every variable in the header, body and buttons. A dynamic URL button counts too.

132001: template doesn’t exist or isn’t approved

“The template does not exist in the specified language or the template has not been approved.” Common causes: a typo in the template name, the wrong language code (en and en_US are different languages to Meta), or a template that is still pending or was rejected.

Fix: copy the exact name and language from WhatsApp Manager and check that the status is Approved. If you created the template in en_US, send it in en_US.

132012: variables in the wrong format

The values you sent don’t use the format the template specifies, for example the wrong parameter type for a header or a body variable.

Fix: compare your request with the template definition and send each parameter in the declared type.

132015 and 132016: paused and disabled templates

When customers block or report a template’s messages, its quality rating drops and Meta can pause it.

• 132015: “Template is paused due to low quality.” Edit it to improve quality, and send again once it’s approved.
• 132016: the template “has been paused too many times due to low quality and is now permanently disabled.” It can’t be revived. Create a new template with different content.

A paused template is a warning about the messages, not just the wording. Before rewriting, check who you sent it to and how often. Our guide to quality ratings and WABA health explains how ratings work.

Other template codes

2388299 catches many first-time template writers. “Hi {{1}}” is fine inside a sentence, but a body that ends with {{2}} is rejected, because Meta doesn’t allow “dangling parameters”. Ending with a full stop or a short phrase fixes it. For the building blocks, see template elements.

Rate limit and quality errors

These errors mean you’re sending too fast, too often to one person, or from a number whose quality has dropped.

130429: throughput limit reached

“Cloud API message throughput has been reached.” Each registered business phone number can send up to 80 messages per second by default, and up to 1,000 per second after Meta’s automatic upgrade, which requires, among other things, an unlimited messaging limit and at least a Medium quality rating (Meta, throughput).

Fix: retry the rejected messages after a pause, with longer waits each time, and slow your overall sending rate. Large campaigns should be sent through a queue that paces requests rather than firing them all at once.

131056: too many messages to the same person

“Too many messages sent from the sender phone number to the same recipient phone number in a short period of time.” This is the “pair rate limit”. Your throughput is meant for messages to many different people, not a burst to one.

Fix: wait before sending to that number again. Messages to other numbers aren’t affected. If an automation sends several messages in a row, combine them into one or add a short delay.

131048: sending restricted because of spam signals

“There are restrictions on how many messages can be sent from this phone number. This may be because too many previous messages were blocked or flagged as spam.”

Fix: stop and look at quality before sending more. Check the number’s quality rating in WhatsApp Manager, pause campaigns to cold or old lists, and review which templates people are blocking. Our guide to maintaining WABA health walks through recovery.

Other limit codes

131064 is worth understanding if you send utility templates with promotional content. Meta describes it as a limit caused by “template classification violations”, so templates filed under the wrong category, such as offers sent as utility, are the first thing to check. Our WhatsApp messaging limits guide explains the tiers.

Account, policy and payment errors

These errors are about your account, not a single message, so every send will fail until they’re resolved.

For restrictions and bans, see account locked or restricted and what to do if your WhatsApp number is banned. For billing, see payments and billing.

Request and access token errors

These are almost always developer-side problems, and they come back in the API response straight away.

If you’re using ChatMitra’s API, you don’t handle Meta tokens yourself, so codes 0, 190 and 200 shouldn’t appear. See the next section for ChatMitra’s own API errors.

Temporary server errors

Sometimes the problem is on Meta’s side. These are the errors worth retrying automatically:

Retry with increasing waits, for example after a few seconds, then longer, then much longer, and stop after a few attempts. A retry loop with no limit can turn a short outage into a flood of duplicate messages once the service recovers.

Retry or fix? A decision table

Every error fits one of three buckets. Sort failures this way before you do anything else:

The third bucket matters most. Resending to people who opted out, or through a disabled template, costs time and can lower your quality rating, which leads to 131048 and restrictions later.

Building error handling for the API

If you send through the API yourself, a small amount of structure turns error codes from a support headache into routine housekeeping. A sensible design has five parts:

1. Store the code and details with every failed message. Keep the message ID (wamid), the recipient, the template name, the code, the details text and the time. Without the details text you lose the most specific part of Meta’s answer, such as which parameter was invalid.
2. Map codes to the three buckets above in one place. A single lookup table, not scattered if statements, means a new code needs one change. Unknown codes should default to “fix, then resend” and raise an alert, not to automatic retries.
3. Retry only the retry bucket, with a cap. Use increasing waits and stop after a fixed number of attempts. Record each attempt, so you can see whether a failure was a one-off or a pattern.
4. Feed permanent failures back into your lists. A 131050 should mark the contact as opted out of marketing. A pattern of 131026 on one contact should flag the number as unreachable on WhatsApp, so the next campaign doesn’t pay the price again.
5. Alert on rates, not single failures. One 131026 is normal. A campaign where 15% of messages fail with 131026, or a sudden run of 131048 or 132015, needs a person to look at it the same day.

Language-specific examples, including retries with backoff, are in our guide to the WhatsApp API in Python.

Errors you see in ChatMitra

ChatMitra shows Meta’s errors where you work, and adds a few of its own.

Where to find the error code:

• Campaign reports. Open a campaign and choose the Failed tab. Each failed contact has a Meta Error Code column and a Reason column, with a link to Meta’s official error documentation. For 131042 (payment), the report links straight to Meta’s payment settings. The Excel export includes the fail reason and error code.
• Team inbox. A failed message shows a red alert icon; hover or tap it to see the reason, which also appears in a red banner under the message.
• Developer API. A failed send returns a fail_reason with Meta’s message.

Smart Auto-Retry. When you create a campaign, you can turn on Smart Auto-Retry to resend automatically to contacts whose messages failed, after an interval you choose (24 hours by default). It skips failures that can never succeed on a retry: 131026, 131031, 131050, 132001, 132007, 132015, 132016, 131037, 130497 and 368. Separately, when Meta returns 130429 (throughput) during a campaign, ChatMitra retries that message a few times within seconds before counting it as failed.

Template rejections. When Meta rejects a template at creation, ChatMitra shows Meta’s error message on screen. The ChatMitra mobile app also shows the rejection reason on the template card.

ChatMitra’s own API errors. If you send through ChatMitra’s developer API, some errors come from ChatMitra, not Meta, and have no Meta code:

See API keys and webhook URL for where to find your token, and our developer documentation for request formats.

How to prevent most errors

Most failures are predictable, and a few habits prevent the majority:

1. Collect numbers in international format, with consent. This cuts 131026 and protects your quality rating. See opt-in best practices.
2. Check the window before sending free-form messages. If the last customer message is more than 24 hours old, use a template. That’s 131047 gone.
3. Keep marketing frequency humane. Fewer, more relevant offers reduce 131049, 131050 and blocks.
4. Version your templates. When you add a variable, create a new template or update every sender at the same time, to avoid 132000.
5. Categorise templates honestly. Promotional content in a utility template risks 131064 and recategorisation.
6. Watch quality weekly. A falling rating shows up before 131048 and 132015 do.
7. Pace large sends. Queue campaigns rather than bursting, to stay under throughput limits (130429).
8. Monitor webhooks, not just responses. Asynchronous failures only appear in the status webhook.
9. Keep billing healthy. An expired card on the Meta account stops every send with 131042.

When to contact support

Contact support when a code isn’t listed here, when a “retry later” error persists for more than an hour or so, or when your account is restricted and you don’t understand why. Check system status first: widespread 1, 2 or 131016 errors usually mean a Meta incident.

To get a fast answer, send:

• the error code and the full details text;
• the message ID (wamid) of an affected message;
• the fbtrace_id, if the error came in an API response;
• the time, with time zone, and the phone number you sent from;
• what changed recently: a new template, a template edit, a new list, a new automation.

Our support page explains how to reach the ChatMitra team.