Skip to main content
请同时检查初始 API 响应以及后续的 whatsapp.message.updated Webhook。YCloud 或 Meta 接收请求并不代表消息已送达。 下表列出了已收录的错误情况。这些内容并非 Meta 可能返回的所有错误。有关当前提供商的最新详情,请参阅 Meta 的错误参考文档。

YCloud 消息发送失败

响应体中的 whatsappApiError

当您通过 YCloud API 发送 WhatsApp 消息时(通常是直接发送 WhatsApp 消息 (POST /v2/whatsapp/messages/sendDirectly) API),可能会收到包含 error.whatsappApiError 字段的错误响应体。 以下是向同一电话号码发送过多消息时,HTTP 状态码为 429 的示例错误响应:
在这种情况下,我们尝试请求 WhatsApp Business API 并收到了错误响应。返回的信息中包含 error.whatsappApiError,以帮助您确定错误原因。

Webhook 负载中的 whatsappApiError

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

WhatsApp Business API 返回的错误代码

whatsappApiError 与 WhatsApp Business Cloud API 错误 完全对应。以下列出了可能通过 YCloud API 返回的部分错误代码。

YCloud API 返回的错误代码

请注意,当错误是由 YCloud 检测到且我们未向 WhatsApp Business API 发起请求时,不会包含 error.whatsappApiError。例如,您提供了一个无效的电话号码,然后收到了错误响应:
error.code 是 YCloud 服务端定义的错误代码之一。 以下列出了 YCloud API 可能返回的部分错误代码:

通过 Webhook 传递的 YCloud 错误代码

如果您使用的是“将 WhatsApp 消息加入队列”(POST /v2/whatsapp/messages)端点,消息可能会因 YCloud 错误而失败。也就是说,Webhook 有效负载中的 whatsappMessage.errorCode 也可能会传达 YCloud 错误代码之一,例如 BALANCE_INSUFFICIENT。 以下是一些可能的错误:

Meta 发送消息失败

WhatsApp Business Cloud API Error页面中列出的错误代码并非都会通过 YCloud API 返回。即使消息已成功提交至 WhatsApp Business API,也仍可能发送失败。Meta 会通过 Webhook 将这些错误通知给 YCloud。您应该配置 Webhook以监听 whatsapp.message.updated 事件,从而接收来自 YCloud 的这些通知。以下是已提交但最终发送失败的消息对应的 Webhook 载荷示例:
whatsappMessage.errorCode 传递了 WhatsApp Business API 错误代码。

通过 Webhook 传递的 Meta 错误代码

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