Skip to main content
YCloud 会对时间窗口内的 API 请求进行限制。限制适用于账户、发送方或一组端点。超出限制的请求将返回 HTTP 429 Too Many Requests 以及标准错误响应。

Messaging API 限制

rps 表示每秒请求数。发送方指 WhatsApp 商业电话号码。 大多数端点的限制为每个账户 200 rps。WhatsApp 发送端点使用上面显示的发送方限制。有关自动升级,请参阅 Meta 的吞吐量文档。

排队发送与直接发送 WhatsApp 消息

YCloud 对这两个 WhatsApp 发送端点分别进行计量。排队端点 /v2/whatsapp/messages 每个发送方最多接受 200 rps,而 YCloud 以 60 rps 的速率将排队消息提交给 Meta。进入队列并不意味着 Meta 已接受或送达该消息。 避免在同一时间通过两个端点使用同一个发送方高速发送消息。排队发送和直接发送仍然使用相同的 WhatsApp 商业电话号码,因此它们的合并流量可能会达到 Meta 的限制并导致失败。

Management API 限制

大多数没有单独文档说明策略的 API 都属于管理 API。这些端点共享一个账户配额: 每秒 200 个请求,每小时 10,000 个请求。两项限制同时生效;您无法在整整一小时内持续保持 200 rps。对一个管理端点的请求会消耗其他管理端点可用的配额。 共享策略包含:
  • /v2/balance
  • /v2/webhookEndpoints/*
  • /v2/whatsapp/businessAccounts/*
  • /v2/whatsapp/phoneNumbers/*
  • /v2/whatsapp/templates/*
  • /v2/whatsapp/messages/{id}
  • 其他未单独说明策略的 API

读取速率限制响应头

YCloud 在大多数 API 响应中包含速率限制信息。请在存在响应头时读取它们,而不是假设每个端点都具有相同的配额。
RateLimit-* 响应头处于测试阶段,可能会发生更改。YCloud 文档中记录的响应头 格式遵循 IETF draft-06 速率限制规范。请将策略 参数视为参考信息,并确保客户端能够兼容额外的 参数。

示例:共享的小时配额已耗尽

账户已耗尽其共享的 每小时 10,000 个请求 配额。请至少等待 1,800 秒,然后再向该配额发送另一个请求。切换到其他管理端点并不会获得新的配额。

处理 429 响应

  1. 暂停共享已耗尽的账户或发送方配额的请求。
  2. 在存在 Retry-After 时予以遵循。在延迟到期之前不要重试。
  3. 降低并发量并添加带有抖动(jitter)的指数退避。
  4. 通过尝试次数或应用程序的截止时间来限制重试。
  5. 记录端点、HTTP 方法、错误 code、requestId 和请求时间。 排除 API 密钥和个人数据。
如果成功的响应包含 Retry-After,请延迟后续请求;不要重新发送已经成功的请求。监控 RateLimit-Remaining 和 RateLimit-Reset 以在配额耗尽前放慢速度。

使用退避和抖动进行重试

此 JavaScript 示例将 Retry-After 视为最短等待时间。退避上限限制了应用程序的抖动延迟;它不会缩短服务器要求的等待时间。尝试次数和延迟设置属于应用程序的选择,而非 API 限制。
仅当操作可安全重试时才应用此示例。对于长时间等待,请使用调度队列,以便工作进程无需一直保持活动状态。

控制并发与重试

使用有界队列和共享的工作进程限制。避免各个独立的重试循环各自假定整个账户或发送方配额完全可用。在限制解除后逐步恢复流量。 重复执行 POST 可能会创建另一个资源或发送另一条消息。请先查看该端点的重试指南以及您保存的结果。在支持的情况下,请保持稳定的 externalId,但不要将其视为通用的幂等性键。保存 YCloud 响应 ID,并在再次发送前对不明确的结果进行对账。 按端点和发送者监控请求量、429 响应、延迟、重试次数以及队列时长。有关排队、对账和防重机制,请参阅 WhatsApp Messages API 最佳实践。