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 速率限制规范。请将策略
参数视为参考信息,并确保客户端能够兼容额外的
参数。示例:共享的小时配额已耗尽
处理 429 响应
- 暂停共享已耗尽的账户或发送方配额的请求。
- 在存在
Retry-After时予以遵循。在延迟到期之前不要重试。 - 降低并发量并添加带有抖动(jitter)的指数退避。
- 通过尝试次数或应用程序的截止时间来限制重试。
- 记录端点、HTTP 方法、错误
code、requestId和请求时间。 排除 API 密钥和个人数据。
Retry-After,请延迟后续请求;不要重新发送已经成功的请求。监控 RateLimit-Remaining 和 RateLimit-Reset 以在配额耗尽前放慢速度。
使用退避和抖动进行重试
此 JavaScript 示例将Retry-After 视为最短等待时间。退避上限限制了应用程序的抖动延迟;它不会缩短服务器要求的等待时间。尝试次数和延迟设置属于应用程序的选择,而非 API 限制。
控制并发与重试
使用有界队列和共享的工作进程限制。避免各个独立的重试循环各自假定整个账户或发送方配额完全可用。在限制解除后逐步恢复流量。 重复执行POST 可能会创建另一个资源或发送另一条消息。请先查看该端点的重试指南以及您保存的结果。在支持的情况下,请保持稳定的 externalId,但不要将其视为通用的幂等性键。保存 YCloud 响应 ID,并在再次发送前对不明确的结果进行对账。
按端点和发送者监控请求量、429 响应、延迟、重试次数以及队列时长。有关排队、对账和防重机制,请参阅 WhatsApp Messages API 最佳实践。
