API 速率限制与 SMTP 限流

​

SMTP 速率限制

​

Web API 速率限制

• 每小时 限制约束您在任意滚动的 60 分钟窗口内对该端点的请求总数。
• 每秒 限制约束瞬时突发速率，防止流量尖峰。
• 若两者同时适用，则必须同时满足。

​

处理 HTTP 429 Too Many Requests

HTTP/1.1 429 Too Many Requests

1. 检测 429：在每个响应中检查 HTTP 状态码。
2. 退避：重试前等待。可从较短延迟（例如 1 秒）开始，遇到连续 429 时按指数退避（例如 2 秒、4 秒、8 秒）。
3. 遵守重置窗口：若响应包含 Retry-After 头，则至少等待该秒数后再重试。
4. 恢复：速率窗口重置后恢复正常请求流量。

// 示例：简单的指数退避
async function sendWithRetry(payload, maxRetries = 5) {
  let delay = 1000; // 起始 1 秒
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch('https://api.effilink.co/v5/sms/sends', {
      method: 'POST',
      headers: { 'ApiKey': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
      body: JSON.stringify(payload),
    });
    if (res.status !== 429) return res;
    await new Promise(r => setTimeout(r, delay));
    delay *= 2; // 每次重试等待时间翻倍
  }
  throw new Error('已达最大重试次数');
}

​

保持在限制内的建议

• 批量发送：/v5/sms/sends 端点单次请求最多接受 100 个收件人。将收件人合并可减少 API 调用总数。详见批量个性化短信。
• 将批量操作错峰执行：若需高频调用（例如同步联系人或触发活动），请将其分摊到一段时间，避免一次性集中发起。
• 缓存读接口响应：对于 /v5/verified_senders 或 /v5/contacts 等端点，可将结果本地缓存，仅在数据变化时刷新，而非高频轮询。
• 监控用量：在应用层跟踪自己的请求速率，主动限流，而非被动应对 429 错误。
• 谨慎使用 transactional 端点：/v5/transactional 的每秒限制严格（10 QPS）。请对出站事务性消息进行排队并以可控速率发送，避免意外被拒。