全局限制

Brevo 对所有 API 端点实施全局速率限制，以保证公平使用和最佳性能。

速率限制档位

免费方案

• 每日限制：300 次请求
• 每小时限制：50 次请求
• 突发限制：10 次请求/分钟
• 邮件额度：300 封/月

入门方案

• 每日限制：20,000 次请求
• 每小时限制：1,000 次请求
• 突发限制：100 次请求/分钟
• 邮件额度：不限

商业方案

• 每日限制：50,000 次请求
• 每小时限制：3,000 次请求
• 突发限制：300 次请求/分钟
• 邮件额度：不限

企业方案

• 每日限制：定制（100,000 以上）
• 每小时限制：定制（10,000 以上）
• 突发限制：定制（1,000 次/分钟以上）
• 邮件额度：不限

速率限制响应头

每个 API 响应都会带上速率限制信息：

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
X-RateLimit-Retry-After: 3600

响应头说明

• X-RateLimit-Limit：当前窗口内允许的请求总数
• X-RateLimit-Remaining：当前窗口内剩余的请求数
• X-RateLimit-Reset：限制重置时刻的 Unix 时间戳
• X-RateLimit-Retry-After：重试前需要等待的秒数

监控用量

查看当前用量

const checkRateLimit = async () => {
  const response = await fetch('https://api.brevo.com/v3/account', {
    headers: { 'api-key': process.env.BREVO_API_KEY }
  });

  console.log({
    limit: response.headers.get('X-RateLimit-Limit'),
    remaining: response.headers.get('X-RateLimit-Remaining'),
    reset: new Date(response.headers.get('X-RateLimit-Reset') * 1000)
  });
};

在仪表板中监控

1. 登录你的 Brevo 仪表板
2. 进入 Settings → API Keys
3. 逐个 API 密钥查看用量
4. 为接近上限的情况设置告警

速率限制重置窗口

• 每日限制：UTC 00:00 重置
• 每小时限制：每小时整点重置
• 突发限制：滑动窗口（最近 60 秒）

应对速率限制

指数退避

const makeRequestWithBackoff = async (url, options, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get('X-RateLimit-Retry-After') || 60;
        const delay = Math.min(1000 * Math.pow(2, i), retryAfter * 1000);

        console.log(`Rate limited. Waiting ${delay}ms before retry ${i + 1}`);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
};

方案升级

如果你持续触达速率限制：

1. 分析用量：查看你调用最多的端点
2. 优化代码：引入缓存和批量处理
3. 考虑升级：需要时切换到更高档位
4. 联系销售：满足企业级需求

速率限制的例外

Webhook 端点

• 不受标准速率限制约束
• 适用独立的 webhook 投递限制

健康检查端点

• /v3/ping 的限制更宽松
• 专为监控和可用性检查设计

批量操作

• 只计为一次请求，但可能有载荷大小限制
• 比多次单独请求更高效