WhatsApp error codes on failed messages: a reference

Every Meta error code you are likely to see on a failed row in Beacon Messenger, what it means in plain words, whether the app retries it, and what to do.

A failed row in the Beacon Messenger message log shows two things from Meta: a number and a short sentence. The number is the error code, and it is the part worth reading, because the sentence is often generic (Unable to deliver message, Something went wrong) while the code is precise. This is the reference we wish Meta's own page were: the codes a Shopify store actually sees, grouped by what you should do about them, with a note on which ones the app retries by itself.

Two kinds of failure land in the log. The first happens at send time: the app calls the Cloud API, Meta answers with an error instead of a message ID, and the row is marked failed with that code. The second happens later: Meta accepted the message, then a status webhook arrives saying it failed, usually because the recipient could not be reached. The row moves from Sent to Failed and picks up the code from the webhook. Same list of codes, different timing, which is why a message can fail an hour after it was sent.

What the app retries without you

Before the list, the retry rule, because it decides whether a code is yours to act on. The app retries a send up to three times, waiting two minutes and then four, when the failure looks temporary: any HTTP 5xx answer from Meta, code 4 (the app has made too many API calls in a short period), and code 130429 (the Cloud API throughput limit was hit). Everything else fails on the first attempt and stays failed, because sending the same thing again would produce the same answer. The search and retry post covers the manual Retry button for the rest.

Codes about the recipient

Recipient-side errors
CodeMeta's titleWhat it meansWhat to do
131026Message undeliverableThe number is not on WhatsApp, has not accepted WhatsApp's current terms, runs an old client version, or has blocked your business. Since 2025 it also covers a recipient who opted out of your marketing messages.Nothing to fix on your side. Check the phone number on the order; if it is right, the customer is not reachable on WhatsApp and the order needs another channel.
131047Re-engagement messageMore than 24 hours have passed since the customer last wrote to you, and the message was not a template. Templates are exempt, so this appears only on free-form sends.Use a template for anything sent outside a conversation the customer started. Beacon Messenger's notifications are templates, so this code is rare in the log.
131056Pair rate limit hitToo many messages to the same recipient in a short window.Usually a burst from a batch action or a loop in a flow. Wait, then resend once; the per-pair limit clears on its own.
131021Recipient cannot be senderThe order's phone number is your own WhatsApp number.A test order placed with the business number. Use a personal number for tests.
131049Meta chose not to deliverMeta's per-user marketing limit stopped the message to keep the recipient's experience healthy.Applies to marketing templates only. Send fewer marketing messages to that person, or use a utility template for order updates.

Codes about the template

Template errors
CodeMeta's titleWhat it meansWhat to do
132001Template does not existNo approved template with that name in that language on your account. Most often the language the app asked for is not one the template has been approved in.Open the template in WhatsApp Manager and compare name and languages with the automation's settings. The language mismatch post is this exact case.
132000Parameter count mismatchThe template has, say, three placeholders and the app sent two, or the other way round.Someone edited the template after mapping it. Re-map the variables in the automation so every placeholder has a Shopify field.
132012Parameter format mismatchA value does not fit the placeholder type: text where a currency is expected, a newline in a header, an empty string.Check the mapped field on the order that failed. An empty variable is the usual culprit; the missing merge fields post has the fallbacks.
132015Template is pausedMeta paused the template because of its quality rating.Nothing sends until the pause lifts. The template status post explains the clock and what to do meanwhile.
132016Template is disabledPaused too often; the template is permanently off.Create a new template with different wording and point the automation at it.
132005Hydrated text too longAfter filling in variables the message exceeds Meta's length limit, typically because of a very long order line list.Shorten the mapped field or use the app's truncated variants of long fields.

Codes about your account and connection

Account and connection errors
CodeMeta's titleWhat it meansWhat to do
0 or 190Auth exception / access token expiredThe token the app uses to call Meta is invalid, expired or revoked.Generate a new permanent token in the Meta business settings and paste it into the app. The credentials post walks through it.
10Permission deniedThe token lacks a permission the call needs, usually whatsapp_business_messaging.Re-create the token with both WhatsApp permissions ticked.
133010Phone number not registeredThe business number has not completed Cloud API registration, or was deregistered.Register the number in WhatsApp Manager under Phone numbers, then retry.
131031Business account lockedMeta restricted the WhatsApp Business Account, often pending a policy review.Open the Business Support Home in Meta and follow the appeal. Nothing in the app can route around it.
131042Business eligibility payment issueNo valid payment method on the WhatsApp Business Account, or a failed charge.Add or fix the payment method in Meta Billing. Free entry-point conversations may still work, but notifications stop.
131048Spam rate limit hitMessaging is paused because of a sharp quality drop, often many blocks in a short time.See the quality rating post. Sending resumes when the rating recovers; use the pause to review templates.
131045Incorrect certificateThe number is registered but its certificate is out of date.Re-register the number in WhatsApp Manager.

Codes about the request or Meta itself

Request and platform errors
CodeMeta's titleWhat it meansRetried?
4API too many callsThe app hit its application-level call limit.Yes, automatically
130429Rate limit hitThe Cloud API throughput limit for your number was hit.Yes, automatically
131000Something went wrongAn unspecified failure on Meta's side.Only if it arrived as a 5xx; otherwise use Retry
131016Service unavailableA Meta outage or maintenance window.Yes, as it is a 5xx
100Invalid parameterSomething in the request was malformed: a phone number with letters, a bad locale code.No; fix the data on the order or in settings
131008Required parameter missingThe request lacked a field Meta needs, which usually points to a template whose header expects a media file that was not provided.No; check the template's header type

If a code appears that is not on this list, Meta's Cloud API error reference is the authoritative page and lists them all, including a dozen that only matter to developers building directly against the API.

Reading a failed row properly

  1. Note whether the row went Failed immediately or after a period at Sent. Immediate means the request was rejected; delayed means the recipient could not be reached.
  2. Read the code, then the details text. The details often name the field or the template, which the title does not.
  3. If the code is 4, 130429 or a server error, check whether the app already retried: the row shows the attempt count. Three attempts and still failed is a real outage, and the outage post covers what to tell customers.
  4. If the code is in the recipient group, the order's phone number is the thing to look at, not the app.
  5. If the code is in the template or account group, fix the cause in WhatsApp Manager or Meta settings first, then press Retry on the affected rows. Retrying before the fix produces the same code again.

The two codes that are not errors

Two rows in the log look like failures and are not. A row marked Skipped has no code at all: the app decided not to send, because the order had no phone number, the customer had not consented, or the order type was excluded, and the skipped reasons post lists them. And a row that sits at Sent without moving to Delivered is not failing; it is waiting for a status webhook that may never arrive if the webhook URL or verify token is wrong. No code will ever appear on it, which is itself the clue.

Frequently asked questions

Does Beacon Messenger retry failed WhatsApp messages automatically?

Only when the failure looks temporary: a server error from Meta, error code 4 (too many API calls) or code 130429 (throughput limit). Those are retried up to three times, two and then four minutes apart. Every other code is final on the first attempt and stays in the log until you press Retry, because resending would get the same answer.

What does WhatsApp error 131026 mean on a Shopify order notification?

Message undeliverable. The number is not on WhatsApp, has not accepted the current terms, uses an outdated app, has blocked your business, or has opted out of your marketing messages. It is a recipient-side condition. Check the number on the order; if it is correct, reach the customer another way.

Why does a message fail an hour after it said Sent?

Meta accepted the message and returned an ID, then later sent a status webhook saying delivery failed, typically with 131026. The app updates the row from Sent to Failed and records the code. It is the same error list as a rejection at send time, just reported after the fact.

Which error codes mean I need to change something in WhatsApp Manager?

The template group (132000, 132001, 132012, 132015, 132016, 132005) and the account group (190, 10, 133010, 131031, 131042, 131048, 131045). Fix the template, token, registration or billing there, then retry the rows. Recipient codes such as 131026 and 131047 need no change in Manager.

More guides