> ## 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.

# 速率限制

> 查看 YCloud API 配额、读取速率限制响应头，并安全重试受限请求。

YCloud 会对时间窗口内的 API 请求进行限制。限制适用于账户、发送方或一组端点。超出限制的请求将返回 HTTP `429 Too Many Requests` 以及标准[错误响应](/zh/api-reference/guides/api-fundamentals/handle-errors)。

## Messaging API 限制

`rps` 表示每秒请求数。发送方指 WhatsApp 商业电话号码。

| 端点 | 速率限制 | 作用域 |
| - | - | - |
| `POST /v2/emails` | 200 rps | 每个账户 |
| `POST /v2/sms` | 200 rps | 每个账户 |
| `POST /v2/voices` | 200 rps | 每个账户 |
| `POST /v2/whatsapp/messages` | 200 rps | 每个发送方 |
| `POST /v2/whatsapp/messages/sendDirectly` | 默认 80 rps；符合条件的自动吞吐量升级后为 1,000 rps | 每个发送方 |

大多数端点的限制为每个账户 200 rps。WhatsApp 发送端点使用上面显示的发送方限制。有关自动升级，请参阅 Meta 的[吞吐量文档](https://developers.facebook.com/docs/whatsapp/cloud-api/overview#throughput)。

### 排队发送与直接发送 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 响应中包含速率限制信息。请在存在响应头时读取它们，而不是假设每个端点都具有相同的配额。

| 响应头 | 含义 |
| - | - |
| `Retry-After` | 重试或发送另一个请求之前需要等待的秒数。 |
| `RateLimit-Limit` | 账户或发送方在所报告时间窗口内的最大配额单位数。 |
| `RateLimit-Policy` | 参考性配额策略及其时间窗口。例如，`100;w=60` 描述了每 60 秒 100 个配额单位。 |
| `RateLimit-Remaining` | 所报告限制中仍可用的配额单位数。 |
| `RateLimit-Reset` | 距离所报告配额重置的秒数。 |

<Note>
  `RateLimit-*` 响应头处于测试阶段，可能会发生更改。YCloud 文档中记录的响应头
  格式遵循 IETF draft-06 速率限制规范。请将策略
  参数视为参考信息，并确保客户端能够兼容额外的
  参数。
</Note>

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

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/2 429
Content-Type: application/json
Retry-After: 1800
RateLimit-Limit: 10000
RateLimit-Policy: 200;w=1;burst=200;algorithm=token_bucket;level=account;scope=management_api, 10000;w=3600;algorithm=fixed_window;level=account;scope=management_api
RateLimit-Remaining: 0
RateLimit-Reset: 1800
```

账户已耗尽其共享的 **每小时 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 限制。

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
async function requestWithBackoff(url, options) {
  const maxAttempts = 5;
  const baseDelayMs = 500;
  const maxBackoffMs = 30_000;

  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;
    if (attempt === maxAttempts - 1) {
      throw new Error("YCloud API rate limit persisted after retries");
    }

    const header = response.headers.get("Retry-After");
    const seconds = header === null ? NaN : Number(header);
    const serverDelayMs = Number.isFinite(seconds) && seconds >= 0
      ? seconds * 1000
      : 0;
    const backoffCap = Math.min(maxBackoffMs, baseDelayMs * 2 ** attempt);
    const delayMs = Math.max(serverDelayMs, Math.random() * backoffCap);
    await response.body?.cancel();
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }
}
```

仅当操作可安全重试时才应用此示例。对于长时间等待，请使用调度队列，以便工作进程无需一直保持活动状态。

## 控制并发与重试

使用有界队列和共享的工作进程限制。避免各个独立的重试循环各自假定整个账户或发送方配额完全可用。在限制解除后逐步恢复流量。

重复执行 `POST` 可能会创建另一个资源或发送另一条消息。请先查看该端点的重试指南以及您保存的结果。在支持的情况下，请保持稳定的 `externalId`，但不要将其视为通用的幂等性键。保存 YCloud 响应 ID，并在再次发送前对不明确的结果进行对账。

按端点和发送者监控请求量、`429` 响应、延迟、重试次数以及队列时长。有关排队、对账和防重机制，请参阅 [WhatsApp Messages API 最佳实践](/zh/api-reference/guides/whatsapp-platform/whatsapp-messages-api-best-practices)。


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