Sign inGet Started

请求速率限制

请求速率限制规定了您的组织在一个时间窗口内可以发出多少请求。使用响应头控制流量节奏,并利用重试延迟从被拒绝的请求中恢复。

限额的划分方式

您的组织在每个策略下共享一个区域限额,涵盖其所有 API 密钥和工作区。创建额外的密钥不会增加容量。不同组织拥有各自独立的限额。

每个请求消耗一个客户策略单位。产品策略具有独立的容量:检索消息状态不会消耗通用的资源检索限额,发送邮件也不会消耗资源创建限额。

登录、密码重置及其他安全敏感操作有额外的滥用保护。供应商检查和连接限制也可能独立于您各计划的请求速率限制而拒绝请求。

分组

普通 API 操作使用以下策略:

策略操作
api_get检索单个资源
api_list列出或搜索集合
api_create创建资源
api_update更新或更新插入资源
api_delete删除资源

产品操作使用命名策略来替代普通的 API 策略。例如 email_send、email_batch、sms_send、whatsapp_send、lookup 和 message_status_read。批量策略计算提交请求数;批量中的收件人数量不会消耗额外的策略单位。有关批量大小限制,请参阅邮件批量发送和 SMS 批量发送。

REST 邮件和 SMTP 提交共享 email_send 容量。一次 SMTP DATA 提交消耗一个单位;SMTP 认证不消耗。如果策略拒绝了提交,服务器将返回临时 452 4.3.1 并附带重试延迟,且不接受该消息。请将消息保留在队列中,并在延迟结束后重试。

创建广播使用 api_create;启动已有广播使用 api_update。向收件人的后台投递不消耗 email_send。发送配额和投递节奏控制仍然是独立的。

voice_call 策略限制入站和出站呼叫的接入。策略耗尽时将拒绝呼叫并记录 calls_per_second_exceeded;不涉及 HTTP 响应。请参阅被拒绝的呼叫。

限额的解析方式

每个产品都有自己的计划,每个计划为该产品的策略设定值:SMS 计划设定 sms_send 和 sms_batch,Voice 计划设定 voice_call,依此类推。等级越高,设定的值越高。共享策略(例如 api_* 组、verify_send、verify_check 和 message_status_read)可由任何产品的计划设定。

某个策略的实际速率按以下顺序确定:

  1. 有效的组织覆盖值(如果存在)。
  2. 在组织当前有效且设定了该策略的产品计划中,取最高值。
  3. 策略默认值,即按量付费的基准值。

覆盖值可以提高或降低速率。无论适用哪个值,策略的时间窗口都保持不变。

从 RateLimit-Policy 响应头中读取您的实际配额,其中包含策略键以及该次调用适用的速率和窗口。如需比较各等级,请从公开计划目录(bird billing plans list --commercial-product sms)或定价页面的对比表中读取每个计划的 rate_limits。

提高限额

如果该策略没有适用的组织覆盖值,请在 Billing and payments > Overview 下,于该策略所属产品的计划页面中升级该产品的计划。请先查看目标计划的 rate_limits:只有当新速率高于您其他计划已提供的值时,新速率才会生效。对于共享策略(例如 api_get 或 verify_send),任何设定了该策略的产品计划都可以提高它。升级付款成功后,更高的速率即生效;具体时间请参阅计划变更与续订。计划还会提高不属于请求速率限制的配额,例如 Voice 并发呼叫数。

无论您选择哪个计划,有效的组织覆盖值都会持续生效,并且可能低于计划的值。如果 RateLimit-Policy 响应头显示的速率低于您计划公布的值,请提供策略键联系支持团队,以审核该覆盖值。

如果您的需求超出最高公开计划所提供的额度,请联系销售,并提供策略键和预期流量。

响应头

请求速率限制评估会在响应中提供两个符合 IETF Structured Fields 格式的响应头(RFC 9651):

代码示例
RateLimit-Policy: "email_send";q=1000;w=60
RateLimit: "email_send";r=842;t=35
响应头含义
RateLimit-Policy适用的策略:q 为配额(最大单位数),w 为窗口秒数。
RateLimit您的当前状态:r 为剩余单位数,t 为窗口重置前的剩余秒数。

带引号的字符串表示策略名称。在此示例中,该组织的有效 email_send 限额为每 60 秒 1000 次提交,剩余 842 次,距重置还有 35 秒。

使用 r 和 t 在收到 429 之前降低请求速度。t 的值是以秒为单位的相对延迟,而非 Unix 时间戳。

触达限额时

您的集成必须将 429 响应作为正常操作的一部分来处理。至少应遵守 Retry-After 并使用退避策略重试。如果客户端还能根据实时 RateLimit 响应头(参见响应头)自行调节速度,则可以避免触达限额。

客户策略耗尽时返回 429 Too Many Requests,其中 Retry-After 以秒为单位,请求速率限制响应头显示 r=0。独立的滥用保护或供应商保护可能在您的客户策略仍有余量时返回 429。根据 Retry-After 决定何时重试;它可能与策略的 t 值不同。

响应体使用标准错误响应格式:

代码示例
{
  "error": {
    "type": "rate_limit_error",
    "code": "E01003",
    "name": "RateLimited",
    "message": "Too many requests. Please retry after the period indicated in the Retry-After header.",
    "doc_url": "https://bird.com/docs/api/errors/E01003",
    "request_id": "req_01ky7qavkff7qr88vadv6bv948"
  }
}

根据 type: rate_limit_error 进行分支判断。人类可读的消息内容可能会变化。从响应头中读取策略键和重试时间:

async function sendWithBackoff(url, headers, payload, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(url, {
      method: "POST",
      headers,
      body: JSON.stringify(payload),
    });
    if (response.status !== 429) return response;
    const retryAfter = Number(response.headers.get("Retry-After") ?? 2 ** attempt);
    await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
  }
  throw new Error("rate limited after max retries");
}

对同一操作的重试,请复用其幂等键。保持请求体不变。

请参阅 SDK 概念了解自动重试和退避行为。

故障模式

请求速率限制器故障时放行:如果 Bird 无法评估限额,请求将继续执行,而不会收到错误的拒绝。请求速率限制保护服务容量。身份认证和授权仍然是安全边界。Bird 端限制器故障不会导致 429。

后续步骤

  • 错误:错误响应格式以及如何根据错误类型进行分支
  • 幂等性:变更类请求的安全重试
  • SDK 概念:自动重试和退避行为