登录开始免费试用
Meta Tech Provider

WhatsApp Cloud API 错误代码

这里列出我们记录的所有 WhatsApp Cloud API 错误代码,并在一张表中说明每个代码的含义,以及重试是否有帮助。大多数情况下没有帮助:这些错误是确定性的,同一个请求会以同样方式失败,而重试循环只会让错误请求最终触发速率限制。

EasyCoexistence 持续监控连接,并将 Meta 的账户和质量事件记录在连接时间线上,因此号码状态引起的错误会在发送失败前显示,而不是失败后才发现。

默认不储存消息Business 应用 + Cloud API为 Claude 和 ChatGPT 提供 MCP2 分钟即可开始使用

请求

代码含义重试
100某个参数不受支持、拼写错误或格式错误。否
131008完全没有包含某个必需参数。否
131009参数存在,但其值被端点拒绝。否
131021发件人和收件人是同一个号码。否
131051不支持该消息类型,通常是 Coexistence 的限制。否
131052Meta 无法下载客户发送的媒体。否
131053Meta 无法上传您发送的媒体。原因在于大小、格式或可访问性。否

模板

代码含义重试
132000参数数量与模板不匹配。否
132001不存在该名称与语言组合的模板。否
132007模板违反消息政策。请改写后重新提交。否
132012参数格式与模板定义不一致。否
132015模板因质量下降被暂停。这是暂时的。等待
132016模板已被永久停用,不会恢复。否

窗口与收件人

代码含义重试
13104724 小时客服窗口已关闭。请发送模板。否
131026收件人完全无法接收该消息。否
131050对方已选择退出。按设计没有任何变通办法。否
130497您的账户被限制向该国家发送消息。否

注册与 PIN

代码含义重试
131045该号码从未注册 Cloud API 消息功能。否
133010该号码未注册。必须完成注册。否
133006号码必须先验证,才能注册。否
133005两步验证 PIN 错误。请停止猜测。否
133008PIN 尝试次数过多。注册被锁定一段时间。等待

访问与账户

代码含义重试
190访问令牌已过期或已失效。否
368账户因违反政策而受到限制。否
131031账户受到限制,或其数据与 Meta 的记录不符。否
131042企业账户的付款问题导致无法发送。否
131049Meta 为保护生态系统健康而拦截了该消息。否

速率限制

代码含义重试
130429已达到账户的消息吞吐量上限。等待
131048触发了垃圾消息速率限制。原因是质量,而不是数量。否
131056您的号码与同一收件人之间的消息过多。否
80007账户已达到管理调用上限,通常是轮询造成的。等待

临时故障

代码含义重试
131016某项 Meta 服务暂时不可用。是
131000未分类的失败。重试一次,然后附上 trace id 上报。是

Coexistence 同步

代码含义重试
2593107已超过聊天记录同步上限。否
2593108在 24 小时同步窗口之外尝试了同步。否

如何阅读重试栏

它有 3 个值,选错值是整份参考资料中代价最高的错误。

否表示失败是确定性的。出问题的是请求、模板或收件人的状态,完全相同的请求会再次产生相同错误,同时消耗您之后会需要的吞吐量。是表示问题出在 Meta 一侧,退避重试确实可以解决。等待表示条件确实存在,但只是暂时的,例如会自行解除的限制或锁定。在解除前重试没有作用,还可能延长限制时间。

为什么大多数代码都不适合重试

因为平台会返回具体代码,而不是笼统的错误。参数格式错误、不存在的模板、已关闭的消息窗口和已选择退出的收件人,都会在响应返回时确定,因此 Meta 会明确指出问题,而不是含糊地失败。

  • 请求问题不会在第二次尝试时自动变正确。
  • 模板问题存在于模板本身,请求无法改变它。
  • 窗口或选择退出问题涉及收件人的状态,而不是您的状态。
  • 账户限制是一项决定,重试不是申诉。

收到这些代码时要记录什么

记录足够的信息,让您无需重现问题也能诊断。这就是 5 分钟修复和整天猜测之间的区别。

  • 完整错误响应,包括 trace id,这是 Meta 支持团队要求的信息。
  • 实际发送的请求正文,而不是您原本打算发送的内容。两者之间的差异通常就是错误所在。
  • phone number id,这样可以区分单个号码的问题和整个账户的问题。
  • 时间戳,这样可以对照该时刻的连接状态检查失败原因。

只存在于 Coexistence 中的代码

有 2 个。它们看起来像普通的发送失败,因此容易让人困惑。2593107 和 2593108 都与聊天记录同步有关,也就是号码首次连接时,从 WhatsApp Business 应用复制近期对话的步骤。

它们不是消息错误,也不表示连接失败。如果同步超过限制或在窗口之外运行,号码仍会保持连接并正常发送,只是复制的历史记录少于预期。把它们看成连接中断,会导致有人断开连接后重新开始,这样只会丢失更多历史记录,而不是恢复记录。

常见问题

哪些错误应该重试?

131016 和 131000,使用指数退避。130429、132015 和 133008 等待后会自行恢复。其他错误都是确定性的。

错误代码是否表示我的号码已断开连接?

通常不是。大多数代码涉及请求、模板或收件人。连接问题通常会以账户和质量 Webhook 的形式出现,而不是发送错误。

什么是 trace id?

它是错误响应中的标识符,让 Meta 支持团队能够找到具体请求。每次失败都应记录它,否则支持工单无法获得处理。

这些代码在每个服务商那里都相同吗?

是。它们来自 Meta 的 Cloud API,因此无论哪家服务商连接该号码,代码都相同。服务商只能影响这些错误能多清楚地传达给您。

准备开始了吗?

几分钟即可设置 WhatsApp Coexistence,而不是几个月。应用会继续在手机上运行。

开始免费试用3 天内不收取任何费用。随时取消。

继续阅读

参考WhatsApp 错误 131047:重新互动消息错误 131047表示客户超过 24 小时未发消息,因此客户服务窗口已关闭,自由文本不会送达。只有 Meta 已批准的消息模板才能重新开启对话。参考WhatsApp 错误 100:参数无效错误 100 表示请求携带了 Meta 不接受的参数:不受支持、拼写错误,或格式不符合该端点的要求。它是确定性的,因此同一请求每次都会以完全相同的方式失败,重试永远无效。参考WhatsApp 错误 131016:服务暂时不可用错误 131016 表示 Meta 一侧的服务暂时不可用。这是少数真正具有暂时性的平​​台错误之一,因此正确做法是指数退避重试,而不是展开调查。参考号码停止工作:如何找出原因已连接号码停止工作时,原因几乎从来不是代码。请按发生频率依次排查:访问令牌过期、重新连接后丢失 Webhook 覆盖设置、14 天不活跃导致断开连接、质量下降,最后是账户限制。参考WhatsApp Webhook 字段,以及各自的去向WhatsApp Business 账户以带名称的字段发送事件。2 项承载对话内容,并发送到您的端点;另 6 项承载运行状态,也是监控的基础。了解两类字段的区别,才能决定架构。指南WhatsApp Coexistence:同一号码使用应用和 APICoexistence 是 Meta 的官方模式,让 WhatsApp Business 应用和 Cloud API 同时使用同一号码。团队仍可通过手机回复,保留相同的对话和历史记录,同时由软件在同一号码上发送和接收消息。无需迁移,也无需更换号码。