> ## 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 错误

> 区分 YCloud 请求错误、Meta 提交错误以及异步发送失败。

请同时检查初始 API 响应以及后续的 `whatsapp.message.updated` Webhook。YCloud 或 Meta 接收请求并不代表消息已送达。

下表列出了已收录的错误情况。这些内容并非 Meta 可能返回的所有错误。有关当前提供商的最新详情，请参阅 [Meta 的错误参考文档](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)。

## YCloud 消息发送失败

### 响应体中的 `whatsappApiError`

当您通过 YCloud API 发送 WhatsApp 消息时（通常是直接发送 WhatsApp 消息 (`POST /v2/whatsapp/messages/sendDirectly`) API），可能会收到包含 `error.whatsappApiError` 字段的错误响应体。

以下是向同一电话号码发送过多消息时，HTTP 状态码为 `429` 的示例错误响应：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "status": 429,
    "code": "TOO_MANY_REQUESTS",
    "message": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
    "target": "whatsappApiError",
    "docUrl": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes",
    "requestId": "req_1KjtKI80IKoaJNa6n6p",
    "whatsappApiError": {
      "message": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
      "type": "OAuthException",
      "code": "131056",
      "fbtrace_id": "A4O5a8RAgePwbcGSu",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Message failed to send because there were too many messages sent from this phone number to the same phone number in a short period of time."
      }
    }
  }
}
```

在这种情况下，我们尝试请求 WhatsApp Business API 并收到了错误响应。返回的信息中包含 `error.whatsappApiError`，以帮助您确定错误原因。

### Webhook 负载中的 `whatsappApiError`

如果您使用的是将 WhatsApp 消息加入队列 (`POST /v2/whatsapp/messages`) API，则绝不会收到包含 `error.whatsappApiError` 的错误响应，因为我们会异步将您的消息提交给 WhatsApp Business API。您可以通过配置监听 `whatsapp.message.updated` 事件的 Webhook 来获取该信息。以下是 Webhook 负载的示例：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "failed",
    "errorCode": "131056",
    "errorMessage": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
    "whatsappApiError": {
      "message": "(#131056) (Business Account, Consumer Account) pair rate limit hit",
      "type": "OAuthException",
      "code": "131056",
      "fbtrace_id": "A4O5a8RAgePwbcGSu",
      "error_data": {
        "messaging_product": "whatsapp",
        "details": "Message failed to send because there were too many messages sent from this phone number to the same phone number in a short period of time."
      }
    },
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp"
  }
}
```

### WhatsApp Business API 返回的错误代码

`whatsappApiError` 与 [WhatsApp Business Cloud API 错误](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax) 完全对应。以下列出了可能通过 YCloud API 返回的部分错误代码。

| 代码 | 描述 | 可能的解决方案 | HTTP 状态 |
| - | - | - | - |
| `2`<br />API 服务 | 由于服务中断或过载导致的暂时性问题。 | 再次重试前，请查看 [WhatsApp Business Platform 状态](https://metastatus.com/whatsapp-business-api) 页面以了解 API 状态信息。 | `503`<br />服务不可用 |
| `100`<br />无效参数 | 请求包含一个或多个不受支持或拼写错误的参数。或者接收方电话号码不是 WhatsApp 电话号码。 | | `400`<br />错误请求 |
| `130429`<br />达到速率限制 | 已达到 Cloud API 消息吞吐量上限。 | 应用已达到 API 的吞吐量限制。请参阅[吞吐量](https://developers.facebook.com/docs/whatsapp/cloud-api/overview/#throughput)。请稍后重试或降低应用发送消息的频率。 | `429`<br />请求过多 |
| `131000`<br />发生错误 | 由于未知错误导致消息发送失败。 | 请重试。如果错误仍然存在，请联系我们提交 [Direct Support](https://business.facebook.com/direct-support) 工单。 | `500`<br />内部服务器错误 |
| `131008`<br />缺少必填参数 | 请求缺少必填参数。 | | `400`<br />错误请求 |
| `131026`<br />消息无法送达 | 无法送达消息。原因可能包括： <br /> <br />• 接收方电话号码不是 WhatsApp 电话号码。<br />• 接收方尚未接受我们最新的服务条款和隐私政策。<br />• 接收方使用的是过期的 WhatsApp 客户端。<br /> | 请通过 WhatsApp 以外的沟通方式，要求该 WhatsApp 用户：<br /> • 确认他们确实可以向您的 WhatsApp 商业电话号码发送消息。<br /> • 确认他们已接受我们最新的服务条款（进入“设置”>“帮助”，或“设置”>“应用信息”，若尚未接受最新条款/政策，系统会提示接受）<br /> • 更新到最新版本的 WhatsApp 客户端。 | `400`<br />错误请求 |
| `131031`<br />账户已被锁定 | 与该应用关联的 WhatsApp 商业账户因违反平台政策已被限制或停用，或者我们无法验证请求中包含的数据与 WhatsApp 商业账户上设置的数据是否一致（例如，请求中包含的两步验证 PIN 码不正确）。 | 请参阅 [政策执行](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/) 文档，了解政策违规行为及解决方法。 | `403`<br />已禁止 |
| `131056`<br />达到（商业账户，个人账户）对频次限制 | 短时间内从发送方手机号向同一接收方手机号发送的消息过多。 | 如果您仍打算向同一手机号发送消息，请等待后再重试操作。您仍然可以向其他手机号发送消息而无需等待。 | `429`<br />请求过多 (Too Many Requests) |
| `132000`<br />模板参数数量不匹配 | 请求中包含的变量参数值数量与模板中定义的变量参数数量不匹配。 | 请确保请求包含了模板中定义的所有变量参数值。 | `400`<br />错误请求 (Bad Request) |
| `132001`<br />模板不存在 | 所指定语言的模板不存在或该模板尚未获得批准。 | 请确保您的模板已获批准，且模板名称和语言区域设置正确。 | `400`<br />错误请求 (Bad Request) |
| `132007`<br />违反模板格式字符政策 | 消息模板内容违反了 WhatsApp 政策。 | 请参阅[拒绝原因](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/#rejection-reasons)以确定可能的违规原因。 | `400`<br />错误请求 (Bad Request) |
| `132012`<br />模板参数格式不匹配 | 变量参数值格式不正确。 | 请求中包含的变量参数值未采用模板中指定的格式。 | `400`<br />错误请求 (Bad Request) |
| `132015`<br />模板已暂停 | 消息模板因质量过低而已暂停，因此无法在模板消息中发送。 | 请编辑模板以提高其质量，并在其获批后重试。 | `400`<br />错误请求 (Bad Request) |
| `132016`<br />模板已被禁用 | 消息模板因质量过低被暂停次数过多，现已被永久禁用。 | 请使用不同的内容创建新模板。 | `400`<br />错误请求 (Bad Request) |
| `133010`<br />电话号码未注册 | 商业电话号码未在 WhatsApp Business Platform 上注册。 | 请在重试前注册该电话号码。 | `400`<br />错误请求 (Bad Request) |
| `130472`<br />用户号码参与了实验 | 作为[实验](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments)的一部分，消息未发送。 | 请参阅[营销消息实验](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/experiments#marketing-message-experiment)。 | `400`<br />错误请求 (Bad Request) |

### YCloud API 返回的错误代码

请注意，当错误是由 YCloud 检测到且我们未向 WhatsApp Business API 发起请求时，不会包含 `error.whatsappApiError`。例如，您提供了一个无效的电话号码，然后收到了错误响应：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "status": 400,
    "code": "PARAM_INVALID",
    "message": "Invalid E.164 phone number: +001",
    "target": "to",
    "docUrl": "https://docs.ycloud.com/en/api-reference/guides/api-fundamentals/handle-errors#error-codes",
    "requestId": "req_69UpMOaMHFrBMGZexYvUDw"
  }
}
```

`error.code` 是 YCloud 服务端定义的[错误代码](/zh/api-reference/guides/api-fundamentals/handle-errors#error-codes)之一。

以下列出了 YCloud API 可能返回的部分错误代码：

| 代码 | 描述 | HTTP 状态 |
| :- | :- | :- |
| PARAM\_INVALID | 一个或多个参数无效。 | `400`<br />错误请求 (Bad Request) |
| PARAM\_MISSING | 缺少一个或多个参数。 | `400`<br />错误请求 (Bad Request) |
| BALANCE\_INSUFFICIENT | 账户余额不足。 | `403`<br />禁止访问 (Forbidden) |
| WHATSAPP\_WABA\_UNAVAILABLE | WhatsApp 商业账户不可用。 | `403`<br />禁止访问 (Forbidden) |
| WHATSAPP\_PHONE\_NUMBER\_UNAVAILABLE | WhatsApp 商业电话号码不可用。 | `403`<br />禁止访问 (Forbidden) |
| WHATSAPP\_TEMPLATE\_UNAVAILABLE | WhatsApp 模板不可用。 | `403`Forbidden |
| UNAUTHORIZED | 未经授权。请确保在“X-API-Key”请求头中使用了正确的 API 密钥。 | `401`<br />未授权 |

### 通过 Webhook 传递的 YCloud 错误代码

如果您使用的是“将 WhatsApp 消息加入队列”(`POST /v2/whatsapp/messages`)端点，消息可能会因 YCloud 错误而失败。也就是说，Webhook 有效负载中的 `whatsappMessage.errorCode` 也可能会传达 [YCloud 错误代码](/zh/api-reference/guides/api-fundamentals/handle-errors#error-codes)之一，例如 `BALANCE_INSUFFICIENT`。

以下是一些可能的错误：

| 错误代码 | 说明 | 可能的解决方案 |
| :- | :- | :- |
| `INTERNAL_SERVER_ERROR` | 因停机或过载导致的暂时性故障。 | 请等待并重试该操作。<br />此错误可能是由于我们调用 WhatsApp Business API 超时所致。 |
| `BALANCE_INSUFFICIENT` | 您的账户余额不足。 | 充值。 |
| `RECIPIENT_UNSUBSCRIBED` | 收件人已取消订阅。 | 尊重用户的退订意愿。仅在用户再次提供有效同意且您的订阅记录已更新后，才可恢复发送消息。 |

## Meta 发送消息失败

[WhatsApp Business Cloud API Error](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax)页面中列出的错误代码并非都会通过 YCloud API 返回。即使消息已成功提交至 WhatsApp Business API，也仍可能发送失败。Meta 会通过 Webhook 将这些错误通知给 YCloud。您应该[配置 Webhook](/zh/api-reference/guides/api-fundamentals/configure-webhooks)以监听 `whatsapp.message.updated` 事件，从而接收来自 YCloud 的这些通知。以下是已提交但最终发送失败的消息对应的 Webhook 载荷示例：

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "evt_eEVCy8eNqD9EvcFI",
  "type": "whatsapp.message.updated",
  "apiVersion": "v2",
  "createTime": "2023-02-22T12:00:00.000Z",
  "whatsappMessage": {
    "id": "63f5d602367ea403f8175a6c",
    "wamid": "wamid.BgNODYxN...",
    "status": "failed",
    "errorCode": "131048",
    "errorMessage": "Message failed to send because there are restrictions on how many messages can be sent from this phone number.This may be because too many previous messages were blocked or flagged as spam.",
    "totalPrice": 0.0,
    "currency": "USD",
    "bizType": "whatsapp"
  }
}
```

`whatsappMessage.errorCode` 传递了 [WhatsApp Business API 错误](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes#error-response-syntax)代码。

### 通过 Webhook 传递的 Meta 错误代码

以下列出了由 YCloud Webhook 传递的、源自 Meta Webhook 的一些常见错误代码：

| 错误代码 | 描述 | 可能的解决方案 |
| - | - | - |
| `131000`<br />发生未知错误 | 由于未知错误，消息发送失败。 | 请重试。如果错误仍然存在，请联系我们以提交 [Direct Support](https://business.facebook.com/direct-support) 工单。 |
| `131026`<br />消息无法送达 | 无法送达消息。原因可能包括：<br /> <br />• 接收方电话号码不是 WhatsApp 电话号码。<br />• 接收方尚未接受我们最新的服务条款和隐私政策。<br />• 接收方使用的 WhatsApp 客户端版本过旧。<br /> | 通过非 WhatsApp 沟通方式，请该 WhatsApp 用户：<br /> • 确认他们确实可以向您的 WhatsApp 商业电话号码发送消息。<br /> • 确认他们已接受我们最新的服务条款（如果尚未接受，进入“设置”>“帮助”，或“设置”>“应用信息”将提示他们接受最新的条款/政策）<br /> • 更新至最新版本的 WhatsApp 客户端。 |
| `131031`<br />账户已被锁定 | 与该应用关联的 WhatsApp 商业账户因违反平台政策已被限制或停用，或者我们无法根据 WhatsApp 商业账户上设置的数据验证请求中包含的数据（例如，请求中包含的两步验证 PIN 码不正确）。 | 请参阅[政策执行](https://developers.facebook.com/docs/whatsapp/overview/policy-enforcement/)文档，以了解政策违规行为以及如何解决这些问题。 |
| `131047`<br />重新互动消息 | 距离接收者最后一次回复发送方号码已超过 24 小时。 | 请改用消息模板向接收者发送由商家发起的会话消息。 |
| `131048`<br />达到垃圾消息速率限制 | 消息发送失败，因为对此电话号码可发送的消息数量存在限制。这可能是因为之前有过多消息被屏蔽或标记为垃圾消息。 | 请在 WhatsApp 管理工具中查看您的质量状态，并参阅[基于质量的速率限制](https://developers.facebook.com/docs/whatsapp/messaging-limits#quality-rating-and-messaging-limits)文档以获取更多信息。 |
| `131049`<br /> | 为维护健康的生态系统互动，此消息未予送达。 | 如果您收到此错误代码并怀疑是由于该限制所致，请勿立即重试。相反，请以递增的时间间隔重试，直到消息成功送达，因为该限制生效的时间长短可能有所不同。<br />有关更多信息，请参阅[单用户营销模板消息限制](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-message-templates#per-user-marketing-template-message-limits)。 |
| `131053`<br />媒体上传错误 | 无法上传消息中使用的媒体文件。 | 由于一种或多种原因，我们无法上传该媒体文件，例如[不支持的媒体类型](https://developers.facebook.com/docs/whatsapp/cloud-api/reference/media#supported-media-types)。 |
| `131050`<br />消息无法送达 | 无法送达消息。该收件人已选择停止在 WhatsApp 上接收来自您商家的营销消息 | |


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