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
| Code | Meta's title | What it means | What to do |
|---|---|---|---|
| 131026 | Message undeliverable | The 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. |
| 131047 | Re-engagement message | More 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. |
| 131056 | Pair rate limit hit | Too 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. |
| 131021 | Recipient cannot be sender | The order's phone number is your own WhatsApp number. | A test order placed with the business number. Use a personal number for tests. |
| 131049 | Meta chose not to deliver | Meta'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
| Code | Meta's title | What it means | What to do |
|---|---|---|---|
| 132001 | Template does not exist | No 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. |
| 132000 | Parameter count mismatch | The 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. |
| 132012 | Parameter format mismatch | A 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. |
| 132015 | Template is paused | Meta 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. |
| 132016 | Template is disabled | Paused too often; the template is permanently off. | Create a new template with different wording and point the automation at it. |
| 132005 | Hydrated text too long | After 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
| Code | Meta's title | What it means | What to do |
|---|---|---|---|
| 0 or 190 | Auth exception / access token expired | The 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. |
| 10 | Permission denied | The token lacks a permission the call needs, usually whatsapp_business_messaging. | Re-create the token with both WhatsApp permissions ticked. |
| 133010 | Phone number not registered | The business number has not completed Cloud API registration, or was deregistered. | Register the number in WhatsApp Manager under Phone numbers, then retry. |
| 131031 | Business account locked | Meta 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. |
| 131042 | Business eligibility payment issue | No 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. |
| 131048 | Spam rate limit hit | Messaging 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. |
| 131045 | Incorrect certificate | The number is registered but its certificate is out of date. | Re-register the number in WhatsApp Manager. |
Codes about the request or Meta itself
| Code | Meta's title | What it means | Retried? |
|---|---|---|---|
| 4 | API too many calls | The app hit its application-level call limit. | Yes, automatically |
| 130429 | Rate limit hit | The Cloud API throughput limit for your number was hit. | Yes, automatically |
| 131000 | Something went wrong | An unspecified failure on Meta's side. | Only if it arrived as a 5xx; otherwise use Retry |
| 131016 | Service unavailable | A Meta outage or maintenance window. | Yes, as it is a 5xx |
| 100 | Invalid parameter | Something in the request was malformed: a phone number with letters, a bad locale code. | No; fix the data on the order or in settings |
| 131008 | Required parameter missing | The 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
- 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.
- Read the code, then the details text. The details often name the field or the template, which the title does not.
- 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.
- If the code is in the recipient group, the order's phone number is the thing to look at, not the app.
- 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
- WhatsApp Business app drops order tools: move orders to Shopify
- A customer replied STOP to a WhatsApp order message. Now what?
- WhatsApp marketing templates leave the Cloud API in October 2027
- WABA to Messaging Account: what changes for Shopify WhatsApp
- Order paid later, refunded or edited: which WhatsApp messages send
- Edited your WhatsApp automation? What queued messages send
- How to add a WhatsApp chat button to your Shopify store (2026)
- How to send Shopify order confirmations and shipping updates over WhatsApp with the official Cloud API
- Cash on delivery on Shopify: confirm orders over WhatsApp before you ship
- Recovering abandoned checkouts on Shopify with WhatsApp, the compliant way
- Why WhatsApp apps get your number banned: linked device vs API
- How a "free" WhatsApp app for Shopify ends up charging you
- Por qué una app de WhatsApp "gratis" para Shopify te cobra
- Pushdaddy or SuperLemon alternative: WhatsApp apps compared
- How to verify Shopify WhatsApp notifications were delivered
- Chat button still on your store after uninstalling the app?
- WhatsApp API pricing changes on Oct 1, 2026: Shopify impact
- Setting up the WhatsApp Cloud API with Meta's MCP and an AI agent
- WhatsApp chat outside business hours: what shoppers should see
- WhatsApp product sharing on Shopify: tracking dark social
- WhatsApp template rejected? Fixing Shopify order templates
- One WhatsApp number or two? Shopify notifications & support
- Shopify Canvas and Beacon Messenger: what works today
- Shopify now collects WhatsApp marketing consent at checkout. Here is what it changes
- Split shipments on Shopify: how many WhatsApp updates to send
- WhatsApp's 250-a-day messaging limit and your Shopify store
- WhatsApp, SMS or email for Shopify order notifications?
- WhatsApp is down: what happens to your Shopify order notifications
- Shopify orders with no phone number: why WhatsApp messages get skipped
- Shopify rollout discounts and WhatsApp order messages
- Add a Track order button to WhatsApp order messages
- Which Shopify orders trigger a WhatsApp message?
- The abandoned checkout timer restarts every time the shopper comes back
- Blank names, twelve-item orders: what WhatsApp merge fields fall back to
- Who looked at your customers' phone numbers? The access log behind a WhatsApp app
- Send a WhatsApp test message before your first order: what the Connect and Test buttons check
- Disconnect, update credentials, app secret: what each does
- COD reply not tagged: how Beacon Messenger matches replies
- WhatsApp template language: why name alone is not enough
- Finding one WhatsApp message in the Beacon Messenger log
- WhatsApp automation is On but nothing sends: a checklist
- Mapping WhatsApp template variables to Shopify order fields
- Every WhatsApp chat button setting in the Shopify theme editor
- WhatsApp template examples for Shopify: order, shipping, COD, cart
- The Share on WhatsApp block, setting by setting
- WhatsApp order messages when customers speak several languages
- Reading the Beacon Messenger dashboard: sent, delivered, failed, skipped
- Shopify batch fulfilment: what happens to 250 WhatsApp shipping messages
- WhatsApp template status: approved, pending, paused, disabled, and what sends
- WhatsApp quality rating: the field on the Connected number card
- COD returns (RTO) on Shopify: confirm orders on WhatsApp first
- WhatsApp display name: what customers see on your order messages
- Shopify Messaging WhatsApp automations vs Beacon Messenger
- OXXO, bank transfer and pay-later orders: when the WhatsApp confirmation goes out
- How many WhatsApp messages will Black Friday send? Sizing your plan
- WhatsApp usernames and BSUIDs: what changes for Shopify order messages
- Reconciling your WhatsApp bill with the Beacon Messenger log
- Track with Shop vs WhatsApp shipping updates on Shopify
- Meta changed my WhatsApp template from utility to marketing
- Shopify's new app security review: what Beacon Messenger can access
- A shopper cancels their own Shopify order: what WhatsApp sends
- Customer erasure in 5 days: what the WhatsApp log keeps
- WhatsApp INR billing deadline: Indian Shopify stores
- WhatsApp template headers: text, image or document?
- Gift orders on WhatsApp: buyer's phone or the recipient's?
- WhatsApp order messages at night: when each one sends
- Downgrading a WhatsApp app plan after peak season: what changes
- Shopify subscription renewals and WhatsApp order messages