The WhatsApp Cloud API errors you will actually hit, and what each one means

Every time I integrate the WhatsApp Cloud API for a client, the same thing happens around week two: a message fails, someone reads the human-readable message field, and the team starts fixing the wrong layer. "Something went wrong" is not a diagnosis. The numeric code in the response body is.

The pattern that saves the most time is knowing which layer each code belongs to. There are only three: your payload is wrong, your template is wrong, or your phone number state is wrong. Once you know the layer, the fix is usually a one-line change.

Two error shapes, and only one of them is a real failure

The Cloud API returns errors in two different structures depending on where the request died.

Request-level errors (a malformed request, a bad token, a missing field) come back as a normal HTTP error with an error object at the top level:

{
  "error": {
    "message": "(#131047) Re-engagement message",
    "type": "OAuthException",
    "code": 131047,
    "fbtrace_id": "A3x9..."
  }
}

Per-recipient errors are the subtler case. You send to 500 recipients, the request returns HTTP 200, and the body shows some messages accepted and others failed with their own embedded error objects. A batch that "succeeded" at the HTTP level can still have delivered to 380 people.

If your integration logs only the HTTP status, it will report a clean run on a day when 120 messages never went out. Log the per-recipient result array and count the failures, or you are flying blind.

Error 131047: the 24-hour window

This is the one everybody meets first. You send a free-form text message to a number that has not messaged you in the last 24 hours, and it fails with 131047 Re-engagement message.

The rule is simple and does not bend: outside the 24-hour customer service window, you can only send template messages that Meta has approved in advance. Inside the window, free-form messages are fine.

The usual wrong instinct is to retry the free-form message. It will fail every time. The fix is architectural: keep a template for every conversation you want to restart — an order update, a reminder, a "you asked about pricing" follow-up — and switch to it when last_inbound_message_at is older than 24 hours. Store that timestamp in your own database from the webhook, because you will want it before you call the API, not after.

Error 132000 / 132001: template does not exist

132000 Template name does not exist in the translation and 132001 Template does not exist mean the name or language code did not match an approved template on that exact WhatsApp Business Account.

Three causes account for nearly all of these, and none of them is a code bug:

• The template was created but never approved — approval is not automatic and can take minutes to hours.
• The language code is wrong. en is not en_US. WhatsApp matches the language tag exactly as it appears in WhatsApp Manager, so en_US in the API against en in Manager fails.
• The API is pointed at a different WABA ID than the one you created the template in. This happens constantly when a team has a test number and a production number.

Before changing any code, open WhatsApp Manager, find the template, and read its exact name and language tag. Copy them verbatim.

Error 132012 / 132015: parameter count and paused templates

132012 Parameter format does not match format in the created template is the one I see most often on newly written integrations. Your template body has three {{1}} {{2}} {{3}} slots; you sent two parameters, or you sent them as named objects when the template uses positional slots.

Two things to know. Parameters are positional and order-sensitive — {{2}} gets the second element of the array, not the parameter that looks like the right one semantically. And a blank string still counts as a parameter, but a missing one does not: if you skip a value because it is empty, the count changes and the message fails.

132015 Template is paused due to low quality is a different animal. The template itself was flagged by recipients and Meta paused it. Retrying achieves nothing; you need a rewritten template, and the old name stays suspended. See the pattern in why WhatsApp templates get rejected — low-quality pauses follow the same logic as rejections.

Error 131026: message undeliverable

131026 Message undeliverable is the most misdiagnosed error in the whole set. It means the recipient cannot receive the message, and there are two realistic reasons: the number does not have WhatsApp, or the number has been opted out / is invalid.

The mistake is treating it as a transient failure and retrying in a loop. Retries produce the same result and, on a large list, drag your quality rating down with them. Validate numbers at capture time — during sign-up or checkout, where you can ask the user to confirm — rather than discovering a 12% invalid rate after a campaign.

Error 131056: rate limit on the pair

131056 Pair rate limit hit is per recipient-and-sender, not global. It fires when you send too many messages to the same number in a short window. If you are firing a confirmation, an update and a reminder within seconds, you will hit it.

Queue per recipient with a small delay rather than blasting in parallel. And note this is a different limit from the messaging limit tier on your number, which is about volume per day across all recipients — fixing one does not fix the other.

Auth, permissions, and the errors that are not message errors

190 Invalid OAuth access token and 100 Invalid parameter usually mean the same downstream thing: an expired system user token, or a token without the whatsapp_business_messaging permission.

Two operational rules that prevent most of these:

1. Use a System User token that does not expire, not a temporary token from the dashboard. Temporary tokens expire in 24 hours and the failure arrives as an unexplained cloud of errors at an awkward hour.
2. Rotate the token on a schedule you control, and log which token ID was used on every request. When something starts failing at 3am, the first question is whether a token changed.

131030 Recipient phone number not in allowed list is expected in development — a test number can only message numbers you added to the allow list. It is the sign you are still on a test number, not a bug.

The debugging habit that makes all of this cheap

Two things turn this from firefighting into a routine.

Log the fbtrace_id on every failure. Meta support asks for it, and it is the only way to have a conversation about a specific message.

Build a small error dashboard before you build anything else. Group failures by code, per day. You will immediately see whether your problem is payload-shaped (132012 climbing after a deploy), template-shaped (132000 flat but persistent), or number-shaped (131026 spread across one imported list). Those are three different people's jobs, and the dashboard tells you whose.

If you are integrating WhatsApp into a product and want the error handling done properly the first time, message me on WhatsApp with what you are building — I have done this enough times to know which failure you will hit first.

Related Reading