Updated on October 25, 2026
WhatsApp API error 131047 means more than 24 hours have passed since the customer’s last message, so the customer service window has closed and free-form messages are no longer accepted. The fix is to send an approved template. The other common codes work the same way: each one points to a cause (recipient, limit, template, account or token) and an action, and Meta recommends handling errors by code, not by HTTP status.
This guide collects the codes you will see most often in production, all checked against Meta’s official error code table, and shows how to separate what can be retried from what should not be.
Where errors show up
The Cloud API returns errors in two places, and sometimes in both:
- In the synchronous response to the send call, when the problem is detected right away: invalid token, wrong parameter, missing template, call rate limit.
- In the
messageswebhook, asynchronously, when the message was accepted but could not be delivered. In that case you get afailedstatus with anerrorsarray.
So a 200 OK on the send call is not enough. A message the API accepted can still fail minutes later. The article on message status via webhook shows how to store these events.
Synchronous error format
{
"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"
}
}The fields that matter:
code: the number your logic should use. Meta advises building error handling around it.error_data.details: the most specific explanation, sometimes with the suggested fix. Always log it.fbtrace_id: the ID to include when you open a ticket with Meta support.error_subcode: deprecated; not returned from API version 16.0 onward.
Webhook error format
When delivery fails, the status event carries the same code. This is the example from the official documentation, with error 131049:
{
"statuses": [
{
"id": "wamid.HBgLNTU4NDk5OTk5OTk5...",
"status": "failed",
"timestamp": "1761400000",
"recipient_id": "5584999999999",
"errors": [
{
"code": 131049,
"title": "This message was not delivered to maintain healthy ecosystem engagement.",
"message": "This message was not delivered to maintain healthy ecosystem engagement.",
"error_data": {
"details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
},
"href": "/documentation/business-messaging/whatsapp/support/error-codes"
}
]
}
]
}Errors not tied to a specific message can arrive in entry.changes.value.errors.
The most common codes and what to do
| Code | What it means | What to do |
|---|---|---|
| 131047 | More than 24 hours since the customer last replied | Send an approved template |
| 131026 | Message undeliverable: recipient is not on WhatsApp, has not accepted the current terms, or uses an outdated app | Confirm the number through another channel; do not retry in a loop |
| 131049 | Marketing message not delivered to keep ecosystem engagement healthy (per-user limit) | Wait at least 24 hours before resending |
| 131050 | Recipient stopped marketing messages from your business | Do not resend; flag as opt-out |
| 131056 | Too many messages from the same number to the same recipient in a short time | Wait and retry for that recipient |
| 130429 | Cloud API throughput limit reached | Slow down and retry with increasing backoff |
| 131048 | Sending restricted because earlier messages were blocked or flagged as spam | Check quality in WhatsApp Manager |
| 130472 | Message not sent because it is part of a marketing message experiment | See the experiment docs; it is not a bug in your code |
| 131042 | Payment method issue | Review the payment account, credit limit, currency and time zone |
| 131051 | Unsupported message type | Use a type the API supports |
| 131053 | Media used in the message could not be uploaded | Check the MIME type and file format |
| 131000 | Unknown error | Retry; if it persists, open a ticket |
| 131016 | Service temporarily unavailable | Check the platform status page and retry |
131047: the 24-hour window is closed
It shows up whenever someone sends free-form text, an image or buttons to a contact who has not messaged the business in the last 24 hours. Each customer message opens the customer service window. Outside it, templates only.
The fix has two parts. In code, check when the last message from that wa_id arrived before sending, and switch to a template after 24 hours. In the product, use a utility or marketing template to restart the conversation: when the customer replies, the window opens again.
131026: message undeliverable
Meta lists three causes: the number is not on WhatsApp, the person has not accepted the latest terms of service or privacy policy, or they use an old version of the app. The API does not tell you which one happened. Resending the same message will not help. Flag the contact, ask for confirmation through another channel (email, SMS) and review where your list came from: a mistyped number falls into the first case.
131049 and 131050: marketing limits
131049 is the per-user limit on marketing templates: Meta holds the message so people who already get a lot of marketing are not flooded. The official advice is to wait at least 24 hours before trying again. Resending right away only produces another failure. There is a dedicated article on per-user marketing limits.
131050 is different: the person chose to stop marketing messages from your business. Do not resend. Treat it as an opt-out and, if you want to track these changes, subscribe to the user_preferences webhook.
131056 and 130429: sending pace
131056 is a pair rate limit: too many messages from your number to the same recipient in a short period. Other recipients are not affected, so only that queue needs to wait.
130429 is the number’s throughput limit. Spread sends over time and retry with exponential backoff.
Template errors (132xxx)
| Code | What it means | What to do |
|---|---|---|
| 132000 | Number of variables sent does not match the template | Send a value for every variable |
| 132001 | Template does not exist in that language or is not approved | Check the name, language code (e.g. en_US) and status |
| 132005 | Translated text is too long | Shorten the translation in WhatsApp Manager |
| 132007 | Template content violates a WhatsApp policy | Revise the text and resubmit |
| 132012 | Variable values are not in the format the template expects | Match the defined format (e.g. header media) |
| 132015 | Template paused for low quality | Edit the template and wait for approval |
| 132016 | Template paused too many times and permanently disabled | Create a new template with different content |
| 132068 | Flow is blocked | Fix the Flow |
| 132069 | Flow throttled: 10 messages using it were already sent in the last hour | Fix the Flow |
132001 is usually a typo: en_us instead of en_US, a capital letter in the name, or a template still under review. 132000 appears when someone edits the template and forgets to update the code that builds the parameters. Flows are covered in WhatsApp Flows.
Token, permission and account errors
| Code | What it means | What to do |
|---|---|---|
| 0 | App user could not be authenticated (token expired or invalidated) | Generate a new token |
| 190 | Access token expired | Generate a new token |
| 3 and 10 | Permission missing or removed | Check permissions in the access token debugger |
| 100 | Unsupported or misspelled parameter | Compare with the endpoint reference |
| 4 | App call rate limit reached | Reduce call frequency |
| 80007 | WhatsApp Business Account (WABA) rate limit reached | Reduce call frequency |
| 368 | Account restricted or disabled for a policy violation | Review policy enforcement and resolve the violation |
| 131031 | Account locked, or submitted data does not match (e.g. wrong two-step PIN) | Check the Health Status API |
| 131037 | 555 number without an approved display name | Get the display name approved |
| 133010 | Number not registered on the platform | Register the number and retry |
If errors 0 and 190 keep appearing, the problem is almost always the token type. Temporary tokens expire; for production, use a permanent system user token.
A note on old codes: lists that circulate online still mention code 470. It does not appear in the current Cloud API table. If your system still handles 470, review it and switch to the current codes.
How to handle errors in code
The practical rule is to split errors into three groups: those that clear up with a retry, those that need a different message, and those that should not be resent.
// Classify Cloud API errors by code
const RETRY = new Set([130429, 131056, 131000, 131016, 4, 80007]);
const USE_TEMPLATE = new Set([131047]);
const WAIT_24H = new Set([131049]);
const DO_NOT_RETRY = new Set([131026, 131050, 132001, 132007, 132015, 132016, 368]);
function decide(code) {
if (RETRY.has(code)) return 'retry_with_backoff';
if (USE_TEMPLATE.has(code)) return 'send_template';
if (WAIT_24H.has(code)) return 'retry_after_24h';
if (DO_NOT_RETRY.has(code)) return 'stop_and_flag';
return 'log_and_review';
}
function onStatus(status) {
if (status.status !== 'failed') return;
for (const err of status.errors || []) {
const action = decide(err.code);
console.log(status.id, status.recipient_id, err.code, err.error_data?.details, action);
}
}Three things to keep in mind:
- Back off on retries. For 130429 and 131056, retry after 1, 2, 4, 8 seconds, with a cap. Retrying without waiting makes the limit worse.
- Store
code,detailsandfbtrace_id. Without them, a support ticket with Meta goes nowhere. - Meta only charges for delivered messages. Even so, each failed marketing delivery can point to a list or quality problem. Track the
failedrate by code over time.
How this works with Vectalk
With Vectalk, webhooks are Meta’s own: the failed status arrives with the errors array and the same codes listed here, so the same handling applies. Vectalk’s own authentication errors are 401 (token missing, invalid or revoked) and 403 (token not allowed for that resource, such as an organization token calling an endpoint that needs an instance token), documented under Authentication. You can also filter message history by status=failed with the List Messages endpoint to review failures.
To get started, create your account at apps.vectalk.com.br/register.
Frequently asked questions
What is WhatsApp error 131047?
It is the “re-engagement” error: the message was not sent because more than 24 hours have passed since the customer last replied. Outside the customer service window, only approved templates can be sent.
Does error 131026 mean the number is not on WhatsApp?
It can, but not only that. Meta also lists a user who has not accepted the latest terms and an outdated app version. The API does not say which cause applies.
Am I charged for messages that fail?
Meta states that it charges only for delivered messages, not for messages sent. A message that ends up failed was never delivered.
Should I resend messages that failed with 131049?
Only after at least 24 hours, as Meta recommends. Resending earlier is likely to fail again.
Where can I find the full list of codes?
On the Error codes page of Meta’s documentation, which also covers template creation, phone number migration and Marketing Messages API errors.
Official sources consulted on October 25, 2026: WhatsApp Cloud API error codes, Status messages webhook reference, WhatsApp Business Platform pricing, Vectalk docs: Authentication, Vectalk docs: List Messages.