深色模式
配额与限流
开放 API 按 Key 限流，每个 Key 每分钟有调用上限。目的是防止某个调用方把平台打满，影响其他客户与后台使用。
一、配额怎么算
| 项 | 说明 |
|---|---|
| 计数维度 | 按 Key 计，不按 IP、不按账号 |
| 时间窗口 | 每分钟 |
| 默认上限 | 每分钟 60 次 |
| 单 Key 调整 | 建 Key 或改 Key 时单独设，留空按平台默认值 |
一次列表调用算一次，翻页也算，所以拉一页 100 条比拉五页 20 条省配额。
二、超出会怎样
超出配额返回 HTTP 429，响应体里的错误码是 quota_exceeded：
json
{ "code": 429, "message": "超出该 Key 的调用配额，请稍后重试" }遇到 429 不要立刻重试，等几秒再试。连续重试会把窗口一直占满，形成雪崩。
三、推荐的拉取节奏
| 场景 | 建议 |
|---|---|
| 每天同步一次 | 每秒 1 次以内，按时间递增翻页，一夜之间能拉完几十万条 |
| 每小时同步 | 用 page_size=100 减少请求数，只拉最近变更的时间段 |
| 分钟级看板 | 只拉汇总口径的数据，不要每次全量翻页 |
| 首次全量 | 放在业务低峰，失败的分页记下来下次补 |
分页上限是每页 100 条，超过按 100 处理。总量很大时按时间窗口切片，每片单独翻页，比一路翻到底更稳。
四、重试策略
| 状态码 | 是否重试 | 做法 |
|---|---|---|
| 429 | 重试 | 等 5 到 30 秒，指数退避，最多 3 次 |
| 500 / 502 / 503 | 重试 | 同上，仍失败则告警 |
| 401 / 403 | 不重试 | 密钥或权限问题，重试没有意义，直接告警 |
| 404 | 不重试 | 资源名或 id 不对，先看 meta 返回的资源清单 |
| 400 | 不重试 | 参数写错，按错误信息改 |
同步任务建议记录每页的最后更新时间与 id，重跑时从断点继续，不要每次从头拉。
五、看用量
「开放 API」菜单里的调用统计按 Key 给出总次数、错误数、平均耗时与状态码分布。用量接近上限时，先在业务侧降低频率或申请调整配额，不要靠加大重试硬扛。