WhatsApp Cloud API error codes: what they mean and how to fix them

You send a WhatsApp message, the API says it was accepted, and then a webhook arrives with a number like 131047 and a one-line title. This guide explains the codes developers hit most often, what to do about each, and which ones are worth retrying at all.

The meanings below come from Meta's own Cloud API error codes page, which we read on 18 October 2026. Meta updates that page, and it lists many more codes than we cover here, so check it for anything not in this guide. If a code isn't listed below, it's because we couldn't confirm it on that page and chose not to guess.

SendFromChat is an independent product and is not affiliated with Meta or WhatsApp. It runs on Meta's official WhatsApp Cloud API. Codes and descriptions are Meta's; the "what to do" advice is ours, and where we're adding to Meta's text we say so.

Where you see these codes

Two places, and they behave differently:

• In the response to your send request. Some problems are caught right away: a bad parameter, an expired token, a missing template.
• Later, in a status webhook. A message can be accepted first and fail afterwards, for example because the person isn't on WhatsApp or Meta held it back. A 202 accepted only means Meta took the message, not that it was delivered. Always listen for status updates (receive WhatsApp replies and statuses with webhooks).

The quick table

Code	What it means	Retry?	First thing to check
131047	More than 24 hours since the person last replied	No	Send a template instead
131026	Recipient can't receive the message	No	Number isn't reachable on WhatsApp
131049	Held back to protect recipient engagement	Not soon	Wait at least 24 hours
131056	Too many messages to one person	Later	Space out messages to them
130429	Throughput limit hit	Yes, slower	Queue and back off
132000	Wrong number of template variables	No	Fix the variables
132001	Template missing in that language, or not approved	No	Name, language, approval
132012	Variable values don't match the template's format	No	Match the template's format
132015 / 132016	Template paused / permanently disabled	No	Template quality
131048	Restrictions on how many messages can be sent from this number	No	Number quality
131042	Payment method problem	No	Billing on the WhatsApp account
190 / 0	Token expired or not authenticated	After fixing	Get a new token
10 / 200–299	Permission not granted or removed	After fixing	App permissions
368	Account restricted or disabled for a policy violation	No	Policy enforcement
131000 / 131016	Unknown error / service unavailable	Yes, a few times	Retry, then check Meta's status

The meanings are our short summaries of Meta's descriptions. The guide is organised by code because that's the stable part of the error.

Message rules

131047: re-engagement window

More than 24 hours have passed since the recipient last replied. Meta's fix: send a template message. This is the single most common code, and it isn't a bug: free-form text is only allowed inside the 24-hour window. See the 24-hour window explained.

Don't retry the same text. Check whether the window is open before you send free-form text, and fall back to an approved template when it isn't.

131026: message undeliverable

Meta lists three causes: the recipient isn't a WhatsApp user, they haven't accepted WhatsApp's latest terms, or they're on an outdated WhatsApp client. Meta's suggestion is to have the person confirm and update, or reach them another way.

From your side this usually means: check the number format (country code, no stray characters), and treat repeated 131026 on the same number as "can't reach on WhatsApp". Retrying the same number every hour won't change that, so move them to another channel.

131049: not delivered to maintain a healthy ecosystem

Meta didn't deliver the message, to maintain healthy ecosystem engagement. Meta's guidance: if you suspect the per-user limit, wait at least 24 hours before resending the template.

What helps: send marketing only to people who opted in and want it (how to collect opt-in), keep the message relevant, and don't immediately re-send to people it was held back for. For the wider picture on pacing and reputation, see WhatsApp bulk messaging without getting banned.

131056: pair rate limit

You sent too many messages from one number to the same recipient in a short time. Meta says to wait and retry, and that other recipients aren't affected. If a workflow can fire several messages for one customer in a row (order placed, paid, packed), combine them or space them out.

130429 and the throughput limit

You hit the Cloud API's throughput limit. Meta says to retry later or send less often. This is the one to handle with a queue: back off, then retry with a delay that grows each time. It's separate from your daily messaging limit tier, which caps how many unique people you can start conversations with in 24 hours.

Template errors

Template problems are the ones you can fully fix in your own code or in the template itself.

• 132000, parameter count mismatch. The number of variables you sent doesn't match the template. Send a value for every {{1}}, {{2}} and so on.
• 132001, template does not exist. Meta says the template is missing in that language, or isn't approved. Check three things: the exact name, the language code (en_US isn't en), and the approval status.
• 132012, parameter format mismatch. The values don't match the format the template expects. Match what the template specifies.
• 132015, template paused. Paused for low quality. Meta says to edit the template to improve quality and resend once it's approved again.
• 132016, template disabled. Paused too many times and now permanently disabled. Create a new template.

For wording that passes review in the first place, read the template approval rules.

Account and quality errors

• 131048, send restriction. There are restrictions on how many messages can be sent from this number. Meta's advice is to check the number's quality status in WhatsApp Manager and review template limits and quality. Stop sending to cold lists while you investigate.
• 131042, payment issue. A problem with the payment method on the WhatsApp Business account, such as no payment method on file. Fix it in your WhatsApp account's billing settings; sending won't recover until you do.
• 368, restricted for policy violations. Your WhatsApp Business account was restricted or disabled for a policy violation. Meta points to its Policy Enforcement documentation. This needs a human to read it, not code.

Authorization errors

• 190, access token expired. Get a new access token. If you copy a temporary token out of a developer console into your server, this is the first error you'll see when it lapses. Use a long-lived system user token instead, and rotate it deliberately.
• 0, authorization. The user couldn't be authenticated: token expired, invalidated or access revoked. Same fix: a new token.
• 10 and 200–299, permission denied. A permission wasn't granted or was removed. Meta suggests checking permissions with its access token debugger.

Unknown and temporary errors

131000 (unknown error) and 131016 (service unavailable) are the ones worth a plain retry. Retry a few times with a delay. 131057 (the business account is in maintenance mode) is similar: wait and retry. For 131016, Meta says to check its status page. If 131000 persists, Meta says to open a Direct Support ticket.

A small decision table in code

This function sorts an error code into "retry", "fix and resend" or "stop". It's our own sketch, not Meta's: it takes the code from a webhook or API error and returns what to do next. We ran the logic locally with sample codes; we have not run it against a live WhatsApp API key, so test it with your own payloads.

const RETRY_WITH_BACKOFF = new Set([130429, 131000, 131016, 131056, 131057]);
const WAIT_24H = new Set([131049]);
const SEND_TEMPLATE_INSTEAD = new Set([131047]);
const FIX_TEMPLATE_CALL = new Set([132000, 132001, 132012]);
const NEEDS_A_HUMAN = new Set([131042, 131048, 368, 132015, 132016]);

export function nextStep(code) {
  if (RETRY_WITH_BACKOFF.has(code)) return "retry-with-backoff";
  if (WAIT_24H.has(code)) return "wait-24h";
  if (SEND_TEMPLATE_INSTEAD.has(code)) return "use-template";
  if (FIX_TEMPLATE_CALL.has(code)) return "fix-request";
  if (code === 131026) return "unreachable-try-another-channel";
  if (code === 190 || code === 0) return "refresh-token";
  if (code === 10 || (code >= 200 && code <= 299)) return "fix-permissions";
  if (NEEDS_A_HUMAN.has(code)) return "alert-a-human";
  return "log-and-review";
}

Keep the last line. A code you haven't seen should be logged with the full error body, not silently retried.

How SendFromChat shows these

SendFromChat sends through Meta's Cloud API, so these are the same underlying codes. Where we can, we translate them into plain words so you don't have to look them up:

• Bulk send reports show a reason for each person who didn't receive the message, for example "Outside the 24-hour window", "Not on WhatsApp, or can't receive messages right now", "Held back by Meta to limit marketing messages to this person" or "Template variables didn't match". A report lets you save those people as a new list or retry the failed ones.
• REST API. Errors come back with a stable type such as window_closed, opted_out, template_not_approved and warmup_limit. When Meta itself refuses a message, the type is whatsapp_rejected and it carries Meta's reason. The full list is in the REST API reference.
• Some mistakes are caught before they reach Meta. Free-form text isn't sent when the window is known to be closed, opted-out contacts aren't messaged, and new numbers are paced under a warm-up limit. A test key (sfc_test_…) runs these checks without sending anything.

We don't claim this removes errors. Meta decides delivery, and some codes, like 131049, can't be engineered away. The aim is to make the reason visible and to avoid the avoidable ones.

Quick checklist when something fails

1. Read the code in the webhook, not only the HTTP status.
2. Is it a retry-able code (130429, 131016, 131000)? Back off and retry a limited number of times.
3. Is it a rule (131047, 131026, 131049)? Retrying won't help; change what you send, to whom, or when.
4. Is it a template code (132000, 132001, 132012)? Fix the call or the template.
5. Is it about the account (131042, 131048, 368, 190)? Fix it in WhatsApp Manager or your token setup, then resume.

Try it

Start the 30-day free trial (no card), connect a number with Continue with Facebook, and use a test key to see how refusals look before you send for real. If you're building in code, see WhatsApp order notifications from your app and the WhatsApp 24-hour window guide. Prefer to ask an assistant? Connect Claude or ChatGPT.