什么是 API 配额与限流响应
配额是面向调用方设定的用量上限：按应用、用户或接口维度限制每秒速率与周期内总量。限流本身只保护服务端，配额还要让调用方知晓余量与重置时间，从而能自行退避。标准做法是在响应头里返回限额、剩余量与重置时间，超限时返回 429 并给出建议重试间隔。
基本信息
| 配额维度 | 应用、租户、用户、接口与套餐等级 |
|---|---|
| 常用响应头 | RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset、Retry-After |
| 超限响应 | HTTP 429，附建议重试时间与配额说明 |
| 配套机制 | 告警通知、临时提额流程、配额使用量看板 |
典型使用场景
- 对外开放平台：按套餐区分调用额度，作为计费与资源分配依据
- 内部服务保护：限制单个调用方的突发流量，避免单点挤占全局
- 批量任务限制：对批量接口设更严格的配额，防止拖垮在线流量
- 防爬与防刷：结合来源与身份维度限制异常高频调用
- 临时提额：大促或数据迁移期间走审批流程临时放宽额度
- 客户端退避：通过响应头让 SDK 自动退避，减少无效重试
超限响应示例
超限响应示例
HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 30
Content-Type: application/json
{
"error": "rate_limit_exceeded",
"message": "当前配额已用尽，请在 30 秒后重试",
"quota": { "limit": 1000, "window": "60s", "scope": "app" }
}配额维度与用途
| 维度 | 用途 | 注意点 |
|---|---|---|
| 应用/客户端 | 对外计费与资源分配 | 与计费口径保持一致 |
| 用户/账号 | 防止单账号滥用 | 共享账号时统计会失真 |
| 接口 | 保护重接口与批量接口 | 不同接口配额需分别设定 |
| 来源 IP | 减轻扫描与爬取压力 | NAT 环境下会误伤同网段用户 |
配额维度要与计费与审计口径一致：若对外按应用计费，限流也应按应用统计，否则对账时无法解释差异。
只在网关限流会留缺口：绕过网关的内部调用与旁路链路不计入配额，仍需在服务侧保留兜底限流。
配额阈值要用真实流量分布定：统计各调用方的速率分位与峰值，把限额设在略高于正常峰值的水平，既保护服务端又减少误伤业务的情况。