Why a WhatsApp message failed: reading the failed status and its errors
A failed status webhook means Meta could not send or deliver a message the business sent through the API. It arrives on the messages field with status failed and an errors array holding code, title, message, error_data.details and href. The code gives the reason: 131047 window closed, 131026 undeliverable, 131049 marketing limit, 131050 marketing stopped, 131042 payment problem.
easyCoexistence connects your WhatsApp Business app number to Meta's Cloud API through Coexistence and passes failed statuses to your server, directly or as signed forwards when automations are on.
More than 24 hours have passed since the recipient last replied; Meta's fix is to send a template instead.
Not delivered to keep ecosystem engagement healthy; wait at least 24 hours before resending the marketing template.
The recipient chose to stop marketing messages from the business; Meta says not to retry.
A failed status omits the contacts array, so correlate the failure through statuses.id.
What Meta charges for: messages are billed when delivered, not when sent.
What does a failed status look like?
Like any status, plus errors. The contacts array is missing, recipient_user_id is left out when the message was sent to a phone number, and there is no pricing object. title and message carry the same text, error_data.details explains it in a sentence, and href points at Meta's error code list. This is Meta's own example, a marketing template stopped by the per-user limit:
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "102290129340398",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"statuses": [
{
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
"status": "failed",
"timestamp": "1751142888",
"recipient_id": "16505551234",
"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"
}
]
}
]
},
"field": "messages"
}
]
}
]
}Which error codes come back most, and what do they mean?
Meta returns errors in the send response, in a failed status, or in both, so the same code can reach you either way, and your handler should read both places. These are the codes that explain most messages that never arrive, with Meta's own reason and the first thing to try; the full list lives in Meta's error code reference:
How should a handler react to each kind of failure?
Sort the code into what to do next before anything retries. A blanket retry turns a marketing opt-out into repeated failures and can extend a block, while dropping a temporary error loses a message that would have gone through a minute later.
- Retry with backoff: 131000 unknown, 131016 service unavailable, 130429 throughput reached.
- Wait first: 131049, at least 24 hours, since early retries can block that user for up to 24 hours more.
- Switch the message: 131047 needs an approved template, because the 24-hour window is closed.
- Stop for this customer: 131050, until a
user_preferencesresume arrives. - Fix the account or content: 131042 payment, 131031 account restricted, 131053 media.
Which failures show up only as a failed status?
The ones Meta decides after accepting the request. The send returns a wamid, and the refusal comes later on this webhook. Meta does not deliver marketing templates to WhatsApp users with United States phone numbers (+1 with a US area code), a marketing template to a customer who stopped marketing messages is processed and then reported as failed with 131050, and the per-user marketing limit reports 131049 the same way.
If the number has no webhook destination, these failures land nowhere you can see and the message simply looks sent. For the full order of checks when a customer got nothing, see the page on WhatsApp API messages not delivered.
What changes on a Coexistence number?
Two things matter. First, the 24-hour window binds only the API. Meta's Coexistence guide says messages sent from the WhatsApp Business app are not subject to the customer service window, so after a 131047 the owner can still answer that customer from the phone, while your system sends an approved template.
Second, throughput is fixed. A number used in the app and the API at once sends at most 20 messages per second, and pushing past that returns 130429. Everything else reads the same as on any Cloud API number: same field, same errors array, same codes.
How do automations and your AI see a failure?
It depends on when Meta says no. A refusal at send time, such as 131047, fails the automation's step: the run shows Failed with Meta's message in the Runs tab, and the owner gets an email so they can answer that customer themselves. Automations also check the window before sending a free-form reply and skip with window_closed instead of trying.
A failure Meta reports afterwards arrives as a failed status at your Forward URL or direct destination, and the run stays as it was. An AI that sent a template through the MCP connector sees the wamid and "sent: true"; ask your system for the status of that wamid, or have the assistant run get_number_health when many messages fail at once.
Common mistakes
- Retrying 131050 in a loop. The customer stopped marketing messages, so each attempt fails the same way until they resume.
- Resending a 131049 marketing template within hours. Meta asks for at least 24 hours, and early retries can block that user for up to 24 hours more.
- Logging only the title. error_data.details carries the specific reason, so store code and details together with the wamid.
- Running without a webhook destination and judging delivery from the send response, which only says Meta accepted the message.
When an automation's reply is refused at send time, the run shows Meta's error and you get an email, and every number is monitored 24/7 for disconnections and quality drops. US$ 9 down to US$ 0.75 per number per month, falling as you add numbers, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
Is a failed message charged by Meta?
Meta's pricing pages say it charges for messages that are delivered, not for messages that are only sent. A failed status carries no pricing object. Charges go to the business's own WhatsApp Business Account; easyCoexistence never marks them up.
Does 131026 mean the customer blocked the business?
Meta's list for 131026 names other reasons: the number is not on WhatsApp, the recipient has not accepted the latest terms, or their WhatsApp version is too old. Meta suggests asking the customer through another channel to check those.
Why does recipient_user_id appear on some failures and not others?
Meta omits it on a failed status when the message was sent to a phone number. When you sent to the customer's BSUID, the failure includes it, and recipient_id may be the one missing.
Can a message fail after it was delivered?
Meta's reference describes failed as a failure to send or deliver. Once a message reached the device, the next statuses you can expect are read, or played for voice messages.
Keep reading
Ready to get started?
Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.
Start Free TrialVerified on