WhatsApp Cloud API吞吐量与速率限制详解

触达限制时会出现哪些错误码？

先把错误码对应到具体的限制，再选择应对方式。

错误码131048和131049与质量和互动有关，而与速度无关，所以更快地重试没有帮助。请参阅WhatsApp API错误码排查。

在OmniChannels.ai API上，上游的拒绝以HTTP 502到达，Meta的错误码和文本在message中；我们自己的速率限制则返回429，并带Retry-After请求头。完整的表格和默认限制请参阅错误与限制。

应该如何排队和重试？

在应用和API之间放一个队列，把速率限制在上限以下，并且只重试以后可能成功的请求。

1. **所有发送都入队。**应用把消息写入队列，由工作进程池来消费。绝不要在一个请求处理程序里循环遍历客户名单。
2. **用令牌桶限速，**速率设在吞吐量之下，为共用同一上限的回复和其他流量留出余量。
3. **先记录每次尝试。**为每条消息写一行记录，以您自己的操作ID作键，保存返回的消息ID，并跳过任何已被接受的消息。
4. **重试临时性失败。**限流和暂时性的服务器错误可以重试；校验错误（400）、认证错误和模板错误不重试。
5. **带抖动的退避。**每次尝试后等待更久，加入随机性以免各工作进程同时重试，并为延迟和尝试次数设上限。
6. **遵守Retry-After，**当响应中包含它时。
7. **超时后重发前先检查。**响应丢失并不意味着消息丢失；请先查看状态事件。

const RETRYABLE = new Set([429, 500, 502, 503, 504]);

async function sendWithBackoff(send, { maxAttempts = 5, baseMs = 500, capMs = 30000 } = {}) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await send();
    if (res.ok) return res;
    if (!RETRYABLE.has(res.status) || attempt === maxAttempts) throw new Error(`failed: ${res.status}`);
    const wait = Math.random() * Math.min(capMs, baseMs * 2 ** (attempt - 1)); // full jitter
    await new Promise((r) => setTimeout(r, wait));
  }
}

Meta的吞吐量页面没有给出针对错误130429的退避规则，所以这属于通行的工程实践。对于携带Meta限流错误码的502，视为可重试；对于任何其他上游错误码，请先阅读消息内容。我们的错误与限制页面有完整的重试表和防重复发送的保护措施。

如何规划一次大批量发送？

开始之前，先算出所需时间、各项限制和Webhook负载。

1. **统计不重复的收件人，**并与您的消息限额比较。如果名单超出您的档位，请先看安全扩量方案。
2. **估算时长。**消息数除以吞吐量就是秒数。以算术为例，若没有其他流量占用上限，10万条消息按每秒80条发送需要1,250秒，约21分钟。
3. **预留容量。**该上限也计入入站消息，所以发送期间要为客户回复留出余量。
4. **确定Webhook服务器的规模。**Meta称，Webhook服务器应能处理三倍于您出站消息的流量，再加上预期的入站流量，延迟中位数不超过250毫秒，且超过1秒的请求不到1%。请参阅Webhook指南。
5. **先检查模板健康状况和质量，**并分批发送，以便在失败或屏蔽增多时及时停止。请参阅如何批量发送WhatsApp消息而不被封号。
6. 大批量发送文件时使用媒体ID而不是链接，这也是Meta的建议。请参阅媒体类型与限制。

在OmniChannels.ai上，批量端点一次请求可接收多个收件人，delay字段可用来限制投递速度。峰值方案请提前与我们的团队商定。

示例：迪拜的一场限时抢购

"Marina Gadgets"（虚构）计划向60,000名已订阅的客户发送限时抢购模板。

1. 他们的限额允许这样做，所以限制因素不是数量，而是速度。按80 mps计算，60,000条消息需要750秒。
2. 他们分成六批，每批10,000条发送，并把速率限制器设为60 mps，为回复留出余量。
3. 有一批出现了若干131056错误，原因是这些客户在同一分钟还收到了订单更新。他们把这些发送推迟几分钟。
4. 工作进程用带抖动的退避重试被限流的请求，并且消息一旦有了ID就不再重试。
5. Webhook端点保存事件并返回200，然后由工作进程更新状态。
6. 每一批之后，他们都先检查失败情况和模板质量再继续。

常见错误有哪些？

• **混淆各种限制。**吞吐量、配对、Graph API和消息限额是不同的问题。
• **立即重试，**这会让号码一直停在上限，使问题延长。
• **以上限速度发送，**导致回复和状态与营销活动争抢容量。
• **超时后不查状态就重发，**造成消息重复。
• **在循环中轮询Graph API端点，**触及每小时限制。
• **Webhook服务器规模不足，**跟不上而引发重试。
• **限制会变化。**本指南给出的是Meta在撰文时的数值。

OmniChannels.ai如何提供帮助

BroadNet是Meta官方的商业解决方案提供商（Business Solution Provider），OmniChannels.ai通过一个API发送WhatsApp消息，提供批量端点、用于限速的delay字段、排期，以及统一格式的Webhook送达状态。分销商的每个子账户有独立的Webhook和额度。峰值方案请与我们的团队一起规划，并阅读WhatsApp API文档、错误与限制和营销活动页面。