> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp 错误代码

> 查询 WhatsApp 消息错误代码并解决通过 YCloud 发送失败的消息。

同时监控 API 响应和 `whatsapp.message.updated` Webhook。消息可能在 YCloud 验证请求时、提交给 WhatsApp 时，或在 WhatsApp 接收消息以便投递后失败。重试前，请根据返回的代码和详细信息排查原因。

## 查找错误代码

| 失败发生位置 | 查看错误的位置 |
| - | - |
| YCloud 在向 WhatsApp 提交前拒绝了请求 | 查看 API 响应中的 `error.code`、`error.message` 和 `error.target`。没有可用的上游 `whatsappApiError`。 |
| WhatsApp 拒绝了通过 `POST /v2/whatsapp/messages/sendDirectly` 进行的同步提交 | 查看 YCloud 错误字段以及 `error.whatsappApiError`（如果存在）。其 `code` 可识别上游 WhatsApp 错误。 |
| 排队消息在通过 `POST /v2/whatsapp/messages` 提交期间失败 | 查看 `whatsapp.message.updated` Webhook 中的 `whatsappMessage.status`、`whatsappMessage.errorCode` 和 `whatsappMessage.errorMessage`。如存在，请检查 `whatsappMessage.whatsappApiError`。 |
| WhatsApp 接受了消息，但随后投递失败 | 在状态为 `whatsappMessage.status: "failed"` 的 `whatsapp.message.updated` Webhook 中查看 `whatsappMessage.errorCode` 和 `whatsappMessage.errorMessage`。处理失败时不要求必须存在 `whatsappApiError` 对象。 |
| 入站消息包含不支持的内容或媒体错误 | 在 `whatsapp.inbound_message.received` Webhook 中检查 `whatsappInboundMessage.errors[]`（如果存在）。每个条目可包含 `code`、`message` 和 `error_data.details`。 |

排队端点在消息提交给 WhatsApp 之前就会返回，因此其初始响应无法报告后续的提交失败。同步端点会报告提交结果，但消息在之后仍可能失败。请求被接收并不代表投递成功；请针对这两个端点都监控 Webhook。

### 读取代码和详细信息

请将 YCloud 请求错误与上游 WhatsApp 错误区分开来。例如，同步响应可能包含 `error.code: "TOO_MANY_REQUESTS"` 和 `error.whatsappApiError.code: "131056"`。前者描述 API 响应；后者则标识发送者与接收者之间的速率限制。

对于失败消息的 Webhook，`whatsappMessage.errorCode` 可以包含 YCloud 代码（例如 `BALANCE_INSUFFICIENT`）或 WhatsApp 代码（例如 `131048`）。请将其保留为字符串格式。

当 `whatsappApiError` 可用时，检查其 `code` 和 `error_data` 以获取具体原因。对于消息 API 错误，`error_data` 可以包含一个 `details` 属性；对于模板 API 错误，它也可以是一个字符串。请匹配错误代码，而不是可能发生变化的错误标题或消息文本。

下面的数字代码描述上游 WhatsApp 失败。有关 YCloud 代码（例如 `UNAUTHORIZED`、`PARAM_INVALID` 或 `BALANCE_INSUFFICIENT`），请参阅 [处理错误](/zh/api-reference/guides/api-fundamentals/handle-errors)。

有关发送端点的信息，请参阅 [发送 WhatsApp 消息](/zh/api-reference/guides/whatsapp-platform/send-whatsapp-message)；有关接收消息状态更新的信息，请参阅 [配置 Webhook](/zh/api-reference/guides/api-fundamentals/configure-webhooks)。

## 发送限制与质量约束

| 代码 | 含义 | 应对措施 |
| - | - | - |
| `80007` | WhatsApp 商业账户已达到其 API 调用上限。 | 减少针对受影响 WABA 的请求，并稍后使用退避重试。 |
| `130429` | 已超出消息吞吐量。 | 降低受影响商业电话号码的发送速率，并在时间上分散发送。 |
| `131048` | 由于垃圾消息或质量信号，发送受到限制。 | 暂停受影响的发送。在恢复前检查电话号码质量、受众许可意愿以及近期负面反馈。 |
| `131056` | 在短时间内从一个商业号码向同一接收者发送了过多消息。 | 等待一段时间后再重试该发送者-接收者对。此特定限制不会阻止向其他接收者发送。 |
| `131064` | 模板分类违规导致了消息发送受限。 | 检查模板类别并纠正错误分类的内容。该限制适用于模板消息和 Direct Send 消息，并将在执行期过后解除。 |

有关质量和接收者维度的限制，请参阅 [质量与投递控制](/zh/documentation/whatsapp-business-platform/pricing-limits-and-quality/quality-and-delivery-controls)。

## 接收者与投递错误

| 代码 | 含义 | 应对措施 |
| - | - | - |
| `130403` | 您的商家已在 WhatsApp 上将该接收者屏蔽。 | 在屏蔽状态解除前请勿重试。在决定是否恢复沟通之前，请先检查屏蔽原因。 |
| `130472` | 作为平台实验的一部分，WhatsApp 拦截了该消息。 | 请勿重复重发同一消息。如果信息具有时效性，请使用其他约定好的沟通渠道。 |
| `131021` | 发送方和接收方的电话号码相同。 | 发送至其他接收方号码。 |
| `131026` | 消息无法送达。可能的原因包括号码未注册 WhatsApp、未接受 WhatsApp 条款或客户端版本过旧。 | 通过其他约定的渠道，请接收方确认其可以向您的业务发送消息、已接受最新的 WhatsApp 条款并已更新 WhatsApp。仅凭该错误代码无法确定具体原因。 |
| `131047` | 24 小时客户服务窗口已过期。 | 发送适当的已批准模板，或等待客户发送新消息后再发送自由格式回复。 |
| `131049` | WhatsApp 拦截了该消息以保护接收方的互动体验。 | 避免立即重试。如果您怀疑是接收方营销限制，请至少等待 24 小时后再考虑发送。首先请检查用户许可和相关性；等待并不能保证消息一定会送达。 |
| `131050` | 接收方已在 WhatsApp 上停止接收来自您商家的营销消息。 | 停止向该接收方发送营销消息。请勿重试发送失败的营销消息。 |

## 模板和 Flow 消息错误

在重试之前，请在 YCloud 中检查确切的模板名称、语言、状态和组件定义。

| 错误代码 | 含义 | 解决方案 |
| - | - | - |
| `132000` | 提供的模板参数数量与模板不匹配。 | 为每个组件提供所需数量的值。 |
| `132001` | 所请求语言的模板缺失或未获批准。 | 检查名称、语言代码、WABA 和批准状态。 |
| `132005` | 模板文本超过允许的长度。 | 根据适用的长度限制检查模板和提供的文本值。 |
| `132007` | 模板内容违反了 WhatsApp 政策。 | 查看报告的违规行为，并在重新提交前更正内容。 |
| `132012` | 模板参数格式与定义不匹配。 | 检查各个组件和参数类型，包括媒体标头和按钮。 |
| `132015` | 由于质量低下，该模板已被暂停。 | 停止使用它发送消息。改进其内容，仅在模板获得批准且可用后才恢复使用。 |
| `132016` | 因反复出现质量暂停，该模板已被永久停用。 | 创建包含不同内容的替代模板，并在发送前解决质量问题。 |
| `132068` | 消息中使用的 Flow 已被屏蔽。 | 检查 Flow 的状态，并在再次使用前解决报告的问题。 |
| `132069` | Flow 已被限流，并已达到其发送额度限制。 | 查看 Flow 的运行健康状况和近期发送记录。解决问题并等待一段时间后再重试。 |

参见[管理 WhatsApp 模板](/zh/api-reference/guides/whatsapp-platform/manage-whatsapp-templates)和[管理 WhatsApp Flow](/zh/api-reference/guides/whatsapp-platform/manage-whatsapp-flows)。

## 消息参数和媒体

| 错误代码 | 含义 | 解决方案 |
| - | - | - |
| `100` | 请求包含不受支持或无效的参数。 | 查看返回的详细信息，并使用 YCloud 端点参考文档更正相应字段。 |
| `131008` | 缺少必需参数。 | 添加错误中指明的字段或组件。 |
| `131009` | 参数值无效。 | 更正错误详细信息中指明的值、格式或长度。 |
| `131051` | 消息类型不受支持。 | 对于出站发送，请使用受支持的 YCloud 消息类型。对于入站消息，请直接处理该不受支持的事件，而不要假定存在常规消息内容。 |
| `131052` | WhatsApp 无法下载用户发送的媒体文件。 | 检查入站错误详细信息。如有需要，请让用户通过其他约定的渠道分享该文件。 |
| `131053` | 无法上传出站消息中使用的媒体文件。 | 请检查实际的文件格式、MIME 类型、大小及可访问性。在重试前修正文件或 URL。 |
| `135000` | WhatsApp 报告了未指定的请求参数错误。 | 请对照 YCloud API 规范检查请求，并保留返回的详细信息。 |

请参阅[发送 WhatsApp 消息](/zh/api-reference/guides/whatsapp-platform/send-whatsapp-message)和[上传 WhatsApp 媒体](/zh/api-reference/guides/whatsapp-platform/upload-whatsapp-media)。

## 账户、电话号码与账单

| 错误码 | 含义 | 解决建议 |
| - | - | - |
| `368`, `131031` | WABA 受到限制或被锁定。对于 `131031`，还可能涉及账户验证数据。 | 请检查账户状态及具体的错误详情。 |
| `130497` | WABA 无法向某些国家/地区的用户发送消息。 | 请检查目的地国家/地区以及针对您业务类别的限制。切勿原样重试不受支持的目的地。 |
| `131042` | WhatsApp 报告了付款或账户账单问题。 | 请检查 WABA 的账单关联状态。这与 YCloud 的 `BALANCE_INSUFFICIENT` 是相互独立的；仅充值可能无法解决该问题。 |
| `131045`, `133010` | 商业电话号码存在注册问题或尚未注册。 | 请在 YCloud 中检查该号码的连接和注册状态。 |
| `131057` | 账户暂时处于维护模式。 | 请等待维护完成，并在退避重试。 |

## 营销消息错误

当 YCloud 通过 Meta 的 Marketing Messages API 提交消息时可能会发生这些错误。请根据返回的详细信息区分模板、同步和路由问题。

| 错误码 | 含义 | 解决建议 |
| - | - | - |
| `131055`, `134100` | 上游营销路由仅接受营销模板。 | 请确认目标消息使用的是 `MARKETING` 模板。效用（utility）和身份验证（authentication）模板需要不同的发送路由。 |
| `131063` | 该账户的 Cloud API 路由上已禁用营销模板。 | 请检查营销发送路由和账户配置。 |
| `134101` | 营销模板仍在同步中。 | 请等待 10 分钟后再重试新创建的模板。 |
| `134102` | 模板不可用，原因是同步未完成或账户资格未达标。 | 请检查账户资格以及模板同步是否已完成。 |
| `132018` | 模板参数验证失败。 | 请更正错误中指出的参数，并在验证通过后再重新发送。 |

对于此路由，`100` 可能表示消息必须是模板，而 `131009` 可能表示参数无效或模板同步尚未完成。请根据返回的详细信息区分这些原因。对于同步未完成的情况，请等待 10 分钟后再重试。

## 临时服务错误

| 错误码 | 含义 | 解决建议 |
| - | - | - |
| `1` | 请求无效或上游服务器错误。 | 请先检查请求。如果请求有效，请排查临时服务问题。 |
| `2`, `131016` | 上游服务暂时不可用或过载。 | 请检查 [WhatsApp Business Platform 状态](https://metastatus.com/whatsapp-business-api)，并在遇到临时故障时进行有上限的退避重试。 |
| `131000` | 未指定的 WhatsApp 故障。 | 请检查服务状态及返回的详细信息。仅在适当时使用有上限的重试。 |

## 重试与升级排查

* 在重试之前，请修正无效参数、模板状态、账户限制以及媒体问题。
* 尊重收件人的退订（opt-out）和屏蔽操作。切勿自动重试此类失败。
* 针对临时故障，请采用指数退避、抖动（jitter）并设置最大重试次数。遵守上文或响应中指定的任何等待时长。
* 在发生超时或收到模棱两可的响应后重新发送前，请核对消息状态以避免重复。`externalId` 是一个关联字段；切勿假定它能用于发送去重。

如果在完成上述排查后错误仍然存在，或者您在账户账单、资格审核或发送路由配置方面需要帮助，请联系[YCloud 支持团队](https://www.ycloud.com/console/#/app/getStarted)。请附上失败发生的时间与时区、端点、具体的错误代码及详细信息、YCloud `requestId`、消息 `id`，以及可用的 `wamid` 或 `fbtrace_id`。请务必去除 API 密钥和不必要的个人数据。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.