登录开始免费试用
Meta Tech Provider

为什么 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 状态直接或通过已签名的转发传递到您的服务器(启用自动化时)。

131047

收件人最后一次回复已超过 24 小时;Meta 的解决办法是改发模板。

131049

为保持生态系统互动健康而未投递;重新发送营销模板前请至少等待 24 小时。

131050

收件人选择停止接收该企业的营销消息;Meta 表示不应重试。

No contacts

failed 状态不含 contacts 数组,请通过 statuses.id 关联失败记录。

Delivered

Meta 的收费依据:消息在投递时计费,而非发送时计费。

failed 状态是什么样子的?

与其他状态相同,但多了 errors。不含 contacts 数组;若消息发送至电话号码,则省略 recipient_user_id;也没有 pricing 对象。title 和 message 内容相同,error_data.details 用一句话解释原因,href 指向 Meta 的错误代码列表。以下是 Meta 提供的示例:一个因每用户限制而被停止的营销模板:

Meta's example: a message that failed with 131049
{
  "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 的错误代码参考:

131026Undeliverable: not a WhatsApp number, terms not accepted, or an outdated WhatsApp version on the recipient's phone.
131047More than 24 hours since the customer last wrote. Send an approved template instead.
131049Held back to keep engagement healthy, usually the per-user marketing limit. Wait 24 hours or more.
131050The customer stopped marketing messages from you. Do not retry.
131042A problem with the payment method on the WhatsApp Business Account.
130472Not sent because the recipient is part of Meta's marketing message experiment.
131053Media could not be uploaded, often an unsupported file type.
131000Unknown error. Try again; if it persists, open a Direct Support ticket.

处理程序应如何应对每种失败?

在任何重试之前,先将代码归类为下一步动作。一刀切的重试会把营销退订变成反复失败,并可能延长封锁期;而放弃临时性错误,则会丢失一分钟后本可成功送达的消息。

  • 采用退避重试: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 已接受该消息。
使用 EasyCoexistence 完成这些操作

当自动化的回复在发送时被拒绝,运行记录会显示 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,而不是几个月。应用会继续在手机上运行。

开始免费试用

验证时间