WhatsApp Cloud API 错误码：含义与排查方法

本指南面向遇到 WhatsApp 消息发送失败的开发者和消息运营团队，帮助您快速判断应该修复请求、等待、更换消息类型，还是直接停止。下列每个错误码都已对照 Meta 的 Cloud API 错误码参考核实；错误码及其表述可能变化，因此在把逻辑写死到代码之前，请先到该页面确认。

WhatsApp Cloud API 的错误会出现在哪里？

错误会出现在两个地方，两处都需要捕获。请求错误会立即在 API 响应中返回；送达错误则稍后通过状态 webhook 到达。

• 同步错误。 发送请求被拒绝，响应中包含一个 error 对象，带有 code、message、type，通常还有 error_data.details。典型例子有 token 过期、缺少参数和模板不匹配。
• 异步错误。 发送请求成功并返回消息 ID，但稍后的 webhook 会以 status: failed 和 errors 数组报告失败。典型例子有服务窗口已关闭、收件人无法送达和营销限制。

一个常见错误是只记录 HTTP 响应。团队看到每个请求都返回了消息 ID，就以为活动发送成功，而实际上有数百条消息在 webhook 中失败了。各状态之间的关系请参阅已发送、已送达、已读与失败状态详解。

最常见的 WhatsApp 错误码有哪些？

下表按“下一步该怎么做”分组，列出多数团队会遇到的错误码。描述是对 Meta 参考文档的转述。

如何修复导致多数活动失败的错误？

实际上，少数几个错误码就造成了大部分失败，每个都有明确的判断规则。

131047：服务窗口已关闭

客户上一次发消息已超过24小时。自由文本、媒体和交互消息只允许在24小时客服窗口内发送；窗口外必须使用已获批准的模板，详见24小时客服窗口。客服在回复旧对话时常会遇到这个错误。请向客服展示窗口状态，并在窗口过期后提供模板选择器。

131026：消息无法送达

先从号码规范化入手：使用国际格式、正确的国家区号，区号之后不带前导零。然后接受一个事实：有些号码就是没有注册 WhatsApp，或者应用版本过旧。对于验证码这类时效性强的消息，请回退到短信。参见 WhatsApp、短信与 RCS 对比。

131049 和 131050：营销限制与退订

两者都影响营销消息。131050 是用户明确选择停止接收营销消息；请将这些用户从营销名单中剔除，并订阅 Meta 的用户偏好 webhook。131049 表示 Meta 为保护用户互动而选择不送达；Meta 建议至少等待24小时，更早的重试很可能再次失败。与其重发，不如降低发送频率并提高内容相关性。

130429、131048 和 131056：发送过快或过多

130429 是吞吐量问题：对消息排队并采用退避策略。131056 是针对收件人的限制：您对同一个人发送过于频繁。131048 是发送号码的质量信号，需要从内容和受众定向上修复，而不是重试。参见消息上限与质量评级。

132000、132001 和 132012：模板不匹配

这些几乎总是集成缺陷。模板名称、语言代码（例如 ar 与 en_US）和变量数量必须与审核通过的内容完全一致。每次修改模板后，都应运行测试，用示例值把每个模板发送一遍。

可直接落地的重试策略

用下面这份清单自动对每次失败分类。

1. 记录错误码、标题、error_data.details、消息 ID、收件人和模板名称。
2. 对 131050、131021、132016、368 和 131031 绝不重试。368 和 131031 要立即通知管理员。
3. 授权类（0、190、10）、参数类（131008、131009、135000）、模板类（132000 至 132015）和计费类（131042）错误，先修复再重试，并提醒责任团队。
4. 130429、4、80007、131016 和 131057 采用带上限的指数退避，退避后重试。
5. 131047（改用模板）和 131026（改用短信或邮件）更换渠道或消息类型。
6. 131049 等待24小时或更久，并复查活动的发送频率。
7. 在活动报告中按错误码汇报失败情况，而不是只给一个“失败”总数。

实际案例：利雅得一家零售商的促销失败

这是一个虚构示例。“Najd Home”向20,000位已同意接收的客户发送营销模板。API 接受了每个请求，但状态 webhook 显示约有1,400条失败。

按错误码分组后，情况一目了然。最大的一组是 131049，团队把这些用户从后续两次发送中剔除，并降低了每周发送频率。较小的一组是 131026；分析发现许多号码保存时带着本地前导零，规范化修复后问题解决。若干 131050 用户被永久移出营销名单。少量 130429 错误来自开场的突发发送，现在改为通过队列控制节奏。

常见错误与客观局限

• 把每次失败都当成可重试。 这会浪费费用，还可能拉低质量评级。
• 把 Meta 的文案写死在代码里。 Meta 会更新标题和说明；请以数字错误码为判断依据，并维护一个可更新的对照表。
• 忽略 error_data.details。 它往往会指出具体出问题的参数。
• 并非每次失败都有解法。 有些收件人无法通过 WhatsApp 触达，而且 Meta 不会解释每一次 131049 的判定。请规划备用渠道。

OmniChannels.ai 如何提供帮助

OmniChannels.ai 由 BroadNet Technologies 提供技术支持，为团队提供摘要和高级两种视图的送达报告，支持筛选和 CSV 导出，便于按活动分析失败消息。当 WhatsApp 发送失败时，渠道回退（fallback）可以通过 RCS 或短信重新发送；模板可在手机模拟界面上预览并跟踪审核进度，从而减少不匹配错误。Webhook 以统一的标准格式报告 FAILED 和 REJECTED 状态，公开的开发者文档中还包含错误与限制参考。