限流与配额
调用与编辑都完全免费，没有付费档位——只有一层防滥用的限流。两个窗口：每分钟的速率，和每天的配额。
两个窗口
| 档位 | 每分钟 | 每天 | 怎么拿到 |
|---|---|---|---|
free |
60 | 50,000 | 自助铸的密钥默认就是这一档 |
trusted |
600 | 1,000,000 | 联系我们，说明用途与量级 |
internal |
不限 | 不限 | 生态内部服务 |
| 匿名（不带密钥） | 100 | 10,000 | 按来源 IP 计 |
两个窗口独立计数：分钟窗按自然分钟切，日配额在 UTC 零点归零。先撞哪个就先返回哪个。
按谁计数
| 你带的凭据 | 计数桶 |
|---|---|
| 应用密钥 | 密钥所属的应用（同一应用的多把密钥共用一个桶） |
| 用户访问令牌 | 那个用户 |
| 什么都不带 | 来源 IP |
把整个用户群从一个服务端出口代理出去时，请务必用用户令牌调用
/v2/me。否则所有人会落进同一个匿名 IP 桶——这正是曾经真实发生过的一次事故：一个站点的全部用户共享一个匿名桶，每天一到量就集体 429。
读响应头
每个 /v2 响应都带当前窗口的余量，不需要靠撞墙来发现自己快到顶了：
RateLimit: limit=60, remaining=57, reset=23
RateLimit-Policy: 60;w=60, 50000;w=86400
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 23RateLimit是 IETF 草案格式：limit是本窗口上限，remaining是剩余次数，reset是秒数（不是时间戳）。RateLimit-Policy同时声明两个窗口：60;w=60是每分钟 60 次，50000;w=86400是每天 50,000 次。X-RateLimit-*是给旧客户端库的同值镜像，三个头都在 CORS 的 expose 列表里。
撞上限之后
code |
含义 | Retry-After |
|---|---|---|
RATE_LIMITED |
分钟窗打满了 | 到本分钟结束的秒数（最多 60） |
QUOTA_EXCEEDED |
今天的配额用完了 | 到 UTC 零点的秒数 |
- 先读
Retry-After，按它等待。不要立刻重试——重试本身也会计数。 - 退避要带抖动。整点齐发的定时任务会在同一秒一起撞墙，然后在同一秒一起重试。
QUOTA_EXCEEDED不要退避重试。今天没有额度了，等待没有意义——该做的是把当天的调用量降下来。
把量降下来的四个办法
- 批量读代替 fan-out。
ids=/refs=一次 100 条，把 N+1 压成 2 次请求。见 字段裁剪与批量读。 - 用条件请求。 带
If-None-Match拿到的304同样计数，但省掉了传输与解析；真正省调用的是把ETag缓存起来、在 TTL 内根本不发请求。见 缓存。 - 别轮询全量。 需要跟住变化就订
/v2/catalog/changes增量信道，不要每晚重扫一遍目录。 - 只要你要的字段。
fields=不省调用次数，但能显著减少你自己这边的解析与存储开销。
这些都做了还是不够，就来谈 trusted 档——描述清楚场景与量级即可，我们更愿意给档位，而不是看着你写重试风暴。