--- title: "WhatsApp Cloud API 错误码：含义与排查方法" description: "整理最常见的 WhatsApp Cloud API 错误码，包括 131047、131026、132001 和 130429：说明每个错误码的含义、修复方法，以及哪些情况下不应该重试，帮助开发和运营团队快速定位发送失败的原因。，并附重试策略清单" canonical: "https://omnichannels.ai/zh/blog/whatsapp-api-error-codes-troubleshooting/" language: "zh" updated: "2026-10-10" publisher: "BroadNet Technologies" brand: "OmniChannels.ai" category: "whatsapp" primaryQuery: "whatsapp cloud api error codes" keywords: ["WhatsApp 错误码", "WhatsApp 错误 131047", "WhatsApp 错误 131026", "WhatsApp 错误 131049", "WhatsApp 错误 132001", "WhatsApp API 消息发送失败", "WhatsApp 频率限制 130429"] published: "2026-10-10" author: "OmniChannels.ai Editorial Team" reviewer: "BroadNet Messaging Solutions Team" readingMinutes: 8 answer: "WhatsApp Cloud API 的错误可分为几大类：授权类（0、190、10）、完整性类（368、131031）、限流类（4、80007、130429、131048、131049、131056）、模板类（132000 至 132016）、收件人类（131026、131047、131050）以及请求类（131008、131009）。先读错误码和 error_data 详情，再做决定：修复后重试、等待后重试、改用模板或其他渠道，或者绝不重试。" takeaways: ["错误 131047 表示24小时客服窗口已关闭；请改发已获批准的模板，而不是自由文本消息。", "错误 131050 表示用户已停止接收营销消息；Meta 明确要求不要重试。", "错误 131049 是针对单个用户的营销限制；Meta 建议至少等待24小时后再重新发送。", "错误 132000 和 132012 几乎总是因为变量数量或格式与已获批准的模板不一致。", "有些错误会在 API 响应中同步返回，有些则稍后通过状态 webhook 以 failed 状态到达，因此两种都必须记录。"] faq: - q: "WhatsApp 错误 131047 是什么意思？" a: "错误 131047 表示自收件人上一次给您的号码发消息以来已超过24小时，客服窗口已关闭，不再允许发送自由文本、媒体和交互消息。请改发已获批准的模板消息，最好是邀请客户回复的实用型（Utility）模板，客户回复后窗口就会重新开启。" - q: "号码明明在 WhatsApp 上，为什么还会收到错误 131026？" a: "Meta 将 131026 描述为无法送达。原因包括号码未注册 WhatsApp、收件人尚未接受最新条款，或 WhatsApp 版本过旧。国家区号错误或使用本地号码格式也是常见原因。请按国际格式校验号码，让客户更新应用，或改用短信或邮件。" - q: "130429 和 131056 有什么区别？" a: "130429 表示您的号码已达到 Cloud API 吞吐量上限，也就是整体发送过快，需要放慢并排队发送。131056 表示您在短时间内向同一收件人发送了过多消息，其他收件人不受影响。130429 靠速率控制解决，131056 则需要拉开对该用户的发送间隔。" - q: "发送失败的 WhatsApp 消息应该自动重试吗？" a: "仅对临时性错误使用指数退避重试，例如 131000（未知）、131016（服务不可用）、130429（吞吐量）以及 4 或 80007（频率限制）。对于 131050（营销退订）、未做任何调整的 131026、模板错误或 368 政策限制，绝不要自动重试。盲目重试会浪费费用、打扰用户，还可能损害质量评级。" - q: "在哪里能看到完整的错误详情？" a: "同步错误会在 API 响应中返回 code、message 和 error_data。异步失败则通过消息 webhook 以 failed 状态到达，其中的 errors 数组包含错误码、标题和详情。请记录完整对象而不只是错误码，因为 details 字段往往会指出具体出问题的参数或媒体。" sources: - title: "错误码 — WhatsApp Cloud API，Meta for Developers" url: "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes" - title: "状态消息 webhook 参考 — Meta for Developers" url: "https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/reference/messages/status" - title: "平台简介：频率限制与加密 — Meta for Developers" url: "https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform" --- # WhatsApp Cloud API 错误码：含义与排查方法 Canonical: https://omnichannels.ai/zh/blog/whatsapp-api-error-codes-troubleshooting/ Language: zh Publisher: OmniChannels.ai by BroadNet Technologies 本指南面向遇到 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 中失败了。各状态之间的关系请参阅[已发送、已送达、已读与失败状态详解](/blog/message-delivery-status-explained/)。 ## 最常见的 WhatsApp 错误码有哪些？ 下表按“下一步该怎么做”分组，列出多数团队会遇到的错误码。描述是对 Meta 参考文档的转述。 | 错误码 | 含义 | 修复方法 | 能否重试？ | |---|---|---|---| | 0 | 无法验证应用用户；token 已过期或被撤销 | 生成新的访问 token | 修复后可以 | | 190 | 访问 token 已过期 | 使用不会过期的系统用户 token，并定期刷新 | 修复后可以 | | 3, 10, 200–299 | 缺少权限或能力 | 在访问 token 调试工具中检查 token 权限 | 修复后可以 | | 368 | WABA 因违反政策被限制或停用 | 在 WhatsApp Manager 中查看政策处置；如有误判请申诉 | 不可以 | | 131031 | 账号被锁定，例如政策或数据验证失败 | 检查账号健康状态；与 Meta 沟通解决 | 不可以 | | 4 | 应用达到 API 调用频率上限 | 降低请求量；检查 App Dashboard | 可以，稍后 | | 80007 | WABA 达到频率上限 | 降低请求量；稍后重试 | 可以，稍后 | | 130429 | 该号码达到 Cloud API 吞吐量上限 | 排队并放慢发送速度 | 可以，配合退避 | | 131048 | 垃圾信息频率限制：该号码发出的消息受到限制 | 在 WhatsApp Manager 中查看质量；改进内容和受众定向 | 不要立即重试 | | 131049 | “为维护健康的生态互动”而未送达 | 至少等待24小时再重新发送 | 24小时内不可以 | | 131056 | 短时间内向同一收件人发送了过多消息 | 拉开对该用户的发送间隔 | 可以，稍后 | | 131000 | 未知错误 | 重试；若持续出现则提交支持工单 | 可以，次数有限 | | 131016 | 服务暂时不可用 | 查看 Meta 状态页；重试 | 可以，配合退避 | | 131008 | 缺少必填参数 | 将请求体与接口参考对照 | 修复后可以 | | 131009 | 参数值无效 | 检查取值，例如电话号码格式或各类 ID | 修复后可以 | | 131021 | 发送方与接收方是同一号码 | 发送给其他号码 | 不可以 | | 131026 | 无法送达消息 | 核对号码，让用户更新 WhatsApp，或改用其他渠道 | 原样不可以 | | 131042 | 支付方式有问题 | 修复计费：付款账户、信用额度、币种 | 修复后可以 | | 131045 / 133010 | 号码未在平台注册 | 注册该企业电话号码 | 修复后可以 | | 131047 | 用户上次回复已超过24小时 | 发送已获批准的模板 | 以模板形式 | | 131050 | 用户已停止接收营销消息 | 不要重试；尊重用户偏好 | 绝不 | | 131051 | 不支持的消息类型 | 使用受支持的类型 | 修复后可以 | | 131052 | 无法下载用户发送的媒体 | 请用户重新发送 | 不适用 | | 131053 | 无法上传您消息中的媒体 | 检查 MIME 类型、大小和 URL | 修复后可以 | | 131057 | 账号处于维护模式 | 等待；吞吐量升级期间可能出现 | 可以，稍后 | | 132000 | 变量数量与模板不一致 | 发送与定义完全一致数量的参数 | 修复后可以 | | 132001 | 该语言下的模板不存在或未获批准 | 检查名称、语言代码和状态 | 修复后可以 | | 132005 | 翻译后的文本过长 | 缩短模板译文 | 修复后可以 | | 132007 | 模板内容违反政策 | 按模板审核规则修改 | 修复后可以 | | 132012 | 变量值格式不正确 | 与预期格式保持一致 | 修复后可以 | | 132015 | 模板因质量低被暂停 | 修改内容以提升质量 | 修改后可以 | | 132016 | 模板在多次被暂停后被永久停用 | 用不同的内容创建新模板 | 不可以 | | 135000 | 请求参数存在未知错误 | 检查请求语法；联系支持团队 | 修复后可以 | ## 如何修复导致多数活动失败的错误？ 实际上，少数几个错误码就造成了大部分失败，每个都有明确的判断规则。 ### 131047：服务窗口已关闭 客户上一次发消息已超过24小时。自由文本、媒体和交互消息只允许在24小时客服窗口内发送；窗口外必须使用已获批准的模板，详见[24小时客服窗口](/blog/whatsapp-24-hour-customer-service-window/)。客服在回复旧对话时常会遇到这个错误。请向客服展示窗口状态，并在窗口过期后提供模板选择器。 ### 131026：消息无法送达 先从号码规范化入手：使用国际格式、正确的国家区号，区号之后不带前导零。然后接受一个事实：有些号码就是没有注册 WhatsApp，或者应用版本过旧。对于验证码这类时效性强的消息，请回退到短信。参见 [WhatsApp、短信与 RCS 对比](/blog/whatsapp-vs-sms-vs-rcs/)。 ### 131049 和 131050：营销限制与退订 两者都影响营销消息。131050 是用户明确选择停止接收营销消息；请将这些用户从营销名单中剔除，并订阅 Meta 的用户偏好 webhook。131049 表示 Meta 为保护用户互动而选择不送达；Meta 建议至少等待24小时，更早的重试很可能再次失败。与其重发，不如降低发送频率并提高内容相关性。 ### 130429、131048 和 131056：发送过快或过多 130429 是吞吐量问题：对消息排队并采用退避策略。131056 是针对收件人的限制：您对同一个人发送过于频繁。131048 是发送号码的质量信号，需要从内容和受众定向上修复，而不是重试。参见[消息上限与质量评级](/blog/whatsapp-messaging-limits-quality-rating/)。 ### 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](/developers/webhooks/) 以统一的标准格式报告 FAILED 和 REJECTED 状态，公开的[开发者文档](/developers/)中还包含[错误与限制](/developers/errors-and-limits/)参考。