为什么 WhatsApp 消息发送失败:读取 failed 状态及其错误
failed 状态的 Webhook 表示 Meta 无法发送或投递企业通过 API 发送的消息。它会通过 messages 字段送达,其中 status 为 failed,并包含一个 errors 数组,数组内有 code、title、message、error_data.details 和 href。代码说明原因:131047 为 24 小时窗口已关闭,131026 为无法投递,131049 为营销限制,131050 为营销已停止,131042 为付款问题。
easyCoexistence 通过 Coexistence 将您的 WhatsApp Business 应用号码连接到 Meta 的 Cloud API,并将 failed 状态直接或通过已签名的转发传递到您的服务器(启用自动化时)。
收件人最后一次回复已超过 24 小时;Meta 的解决办法是改发模板。
为保持生态系统互动健康而未投递;重新发送营销模板前请至少等待 24 小时。
收件人选择停止接收该企业的营销消息;Meta 表示不应重试。
failed 状态不含 contacts 数组,请通过 statuses.id 关联失败记录。
Meta 的收费依据:消息在投递时计费,而非发送时计费。
failed 状态是什么样子的?
与其他状态相同,但多了 errors。不含 contacts 数组;若消息发送至电话号码,则省略 recipient_user_id;也没有 pricing 对象。title 和 message 内容相同,error_data.details 用一句话解释原因,href 指向 Meta 的错误代码列表。以下是 Meta 提供的示例:一个因每用户限制而被停止的营销模板:
{
"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"
}
]
}
]
}哪些错误代码最常出现,它们分别代表什么?
Meta 会在发送响应、failed 状态中返回错误,或两者同时返回,因此同一代码可能通过任一途径送达,您的处理程序应同时读取两处。以下是导致大多数消息无法送达的代码,附上 Meta 给出的原因及首先应尝试的做法;完整列表见 Meta 的错误代码参考:
处理程序应如何应对每种失败?
在任何重试之前,先将代码归类为下一步动作。一刀切的重试会把营销退订变成反复失败,并可能延长封锁期;而放弃临时性错误,则会丢失一分钟后本可成功送达的消息。
- 采用退避重试:131000 未知错误、131016 服务不可用、130429 已达吞吐上限。
- 先等待:131049,至少 24 小时,因为过早重试可能使该用户再被封锁最多 24 小时。
- 更换消息方式:131047 需要已获批准的模板,因为 24 小时窗口已关闭。
- 停止对该客户发送:131050,直到收到
user_preferences的 resume 事件为止。 - 修复账户或内容:131042 付款问题、131031 账户受限、131053 媒体问题。
哪些失败只会以 failed 状态显示?
Meta 在接受请求之后才作出判定的那些失败。发送请求会返回 wamid,而拒绝结果稍后通过此 Webhook 送达。Meta 不会向拥有美国电话号码(+1 加美国区号)的 WhatsApp 用户投递营销模板;发送给已停止接收营销消息的客户的营销模板会先被处理,然后以 131050 报告为失败;每用户营销限制同样以 131049 报告。
如果该号码没有 Webhook 目的地,这些失败将无处可见,消息看起来就像已成功发出。若客户未收到任何消息,请参阅关于 WhatsApp API 消息未送达的页面,了解完整的检查顺序。
Coexistence 号码有何不同?
有两点需要注意。第一,24 小时窗口只约束 API。Meta 的 Coexistence 指南说明,从 WhatsApp Business 应用发送的消息不受客服窗口限制,因此出现 131047 后,所有者仍可通过手机回复该客户,而您的系统则发送已获批准的模板。
第二,吞吐量有固定上限。同时在应用和 API 中使用的号码,每秒最多发送 20 条消息,超出则返回 130429。其他方面与任何 Cloud API 号码无异:相同字段、相同的 errors 数组、相同的代码。
自动化和您的 AI 如何看待失败?
这取决于 Meta 何时拒绝。发送时的拒绝(例如 131047)会使自动化的该步骤失败:运行记录选项卡中显示 Failed 并附带 Meta 的消息,所有者会收到电子邮件,以便亲自回复该客户。在发送自由格式回复前,自动化还会检查窗口,并以 window_closed 跳过,而不是尝试发送。
Meta 事后报告的失败,会以 failed 状态送达您的转发 URL 或直接目的地,运行记录保持原样。通过 MCP 连接器发送模板的 AI,会看到 wamid 和“sent: true”;请向您的系统查询该 wamid 的状态,或在大量消息同时失败时,让助手运行 get_number_health。
常见错误
- 以循环方式重试 131050。客户已停止接收营销消息,因此每次尝试都会以同样方式失败,直到对方恢复接收为止。
- 在数小时内重新发送 131049 营销模板。Meta 要求至少间隔 24 小时,过早重试可能使该用户再被封锁最多 24 小时。
- 只记录 title。error_data.details 包含具体原因,因此请将 code 和 details 与 wamid 一并存储。
- 在没有 Webhook 目的地的情况下运行,并仅凭发送响应判断投递情况;而发送响应只表明 Meta 已接受该消息。
当自动化的回复在发送时被拒绝,运行记录会显示 Meta 的错误,您也会收到电子邮件;每个号码都会全天候 24/7 监控断开连接和质量下降的情况。每个号码每月 US$ 9 起,号码越多价格越低,最低降至 US$ 0.75,前 3 天免费试用。
常见问题
Meta 会对失败的消息收费吗?
Meta 的定价页面说明,只对成功投递的消息收费,不对仅发送的消息收费。failed 状态不包含 pricing 对象。费用计入企业自己的 WhatsApp Business 账户,easyCoexistence 从不加价。
131026 是否意味着客户已屏蔽该企业?
Meta 对 131026 的说明列出了其他原因:该号码不在 WhatsApp 上、收件人尚未接受最新条款,或其 WhatsApp 版本过旧。Meta 建议通过其他渠道向客户核实这些情况。
为什么有些失败中会出现 recipient_user_id,有些则没有?
当消息发送至电话号码时,Meta 会在 failed 状态中省略它。若您发送至客户的 BSUID,失败记录会包含它,而可能缺失的是 recipient_id。
消息在送达后还会失败吗?
Meta 的参考文档将 failed 定义为发送或投递失败。消息一旦到达设备,您接下来可能收到的状态是 read,语音消息则为 played。
继续阅读
准备开始了吗?
几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。
开始免费试用验证时间