限流与重试

每个应用有独立的速率配额，超额请求会立即返回错误，不会被排队。

默认配额

维度	默认值	错误码
每分钟	100 次	200101 RATE_LIMIT_EXCEEDED
每天	10000 次	200102 DAILY_LIMIT_EXCEEDED

可联系管理员申请提升配额。

配额响应头

每次成功调用，服务端会在响应头返回当前配额状态：

Header	含义
X-RateLimit-Limit	每分钟上限
X-RateLimit-Remaining	当前分钟剩余
X-RateLimit-Reset	下次重置 Unix 时间戳（秒）
X-RateLimit-Daily-Limit	每日上限
X-RateLimit-Daily-Remaining	今日剩余
X-Request-Id	请求追踪 ID（出错时把这个 ID 反馈给我们能更快定位）

客户端建议

1. 平滑请求

把批量任务摊到时间窗：

const delay = Math.ceil(60_000 / 100)  // 600ms 间隔确保不超额
for (const item of items) {
  await callApi(item)
  await sleep(delay)
}

2. 优先使用批量接口

许多读接口提供批量入口（如 POST /openapi/v2/resource/batch，单次最多 50 个 ID），优先使用以减少调用次数。

3. 使用增量同步

需要全量数据时，不要遍历分页。改用 GET /openapi/v2/resource/sync，按 updateTime cursor 拉取增量。

4. 退避重试

遇到 200101 / 200102，不要立即重试，按指数退避：

async function callWithBackoff(fn, retries = 3) {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn()
    } catch (e) {
      if (e?.code === 200101 || e?.code === 200102) {
        // 1s → 2s → 4s
        await sleep(Math.pow(2, i) * 1000)
        continue
      }
      throw e
    }
  }
  throw new Error('Rate limit exhausted after retries')
}

5. 监控 X-RateLimit-Remaining

在中间件层观察该响应头，当余量 < 20% 时主动降速。

突发流量保护

平台后端基于 Redis 滑动窗口，分布式可见。客户端短时间并发不会"绕过"配额。

IP 白名单

除速率配额外，可在 我的应用 → IP 白名单 配置允许调用来源。支持精确 IP 与通配符（如 192.168.1.*）。未匹配请求返回 200103 IP_NOT_ALLOWED。