限流与免费配额

每分钟限流

默认每个密钥 60 请求/分钟，允许短时突发至 120。限制维度是密钥；不同密钥有各自令牌桶，但不要用创建多个密钥规避限制。运营可为单个密钥配置覆盖值。

响应头

X-Request-Id: req_a1b2c3d4
ETag: W/"1234-AbCdEf"
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1787702460
Retry-After: 2

X-RateLimit-Reset 是 Unix 秒。除每次读取都会把自身计入用量的 GET /v1/usage 外，成功 GET 的 ETag 可放进下一次请求的 If-None-Match；内容未变化时返回 304。Retry-After 只在 429 返回；等待指定秒数后再试，并加少量随机抖动。

月度防滥用上限

API 不单独计费，所有套餐都包含。每个套餐仍有足够宽松的自然月调用上限，用来截断失控循环。GET /v1/usage 给机器读取已用与剩余量；桌面客户端配额区显示同源数字。超限返回 429 和 api_quota_exceeded。

调用计数口径

响应                              计入 api_calls_month
2xx                               是
4xx（无效密钥的 401 除外）       是
304（If-None-Match 命中）         否
429                               否
5xx                               否
无效密钥的 401                    不计租户，仍参与 IP 限流

4xx 计数是为了避免错误请求持续压库；If-None-Match 命中 ETag 的 304 不计月额度，但仍受每分钟限流；429 不计，避免「越限流越扣、越扣越出不来」；5xx 是服务端责任，不进入调用方额度。拉 N 页就是 N 次调用，批量同步请提高 limit（最大 1000）。