开放平台API请求速率限制说明文档

文档说明

本文档定义了开放平台API的请求速率限制（限流）规则，明确不同维度、不同时间粒度下的API调用频次上限，帮助开发者合理控制调用频率，避免触发限流机制导致接口调用失败。

核心定义

1. 限流维度

维度标识	维度名称	维度说明
USER	用户维度	基于调用方的用户唯一标识（如用户ID）进行限流，限制单个用户的API调用频次
APP	应用维度	基于调用方的应用唯一标识（如API Key关联的应用ID）进行限流，限制单个应用的API调用频次
GLOBAL	全局维度	基于开放平台整体服务容量进行限流，限制全平台所有调用方的总API调用频次

2. 时间粒度

时间标识	时间单位	说明
SECOND	秒	以“1秒”为时间窗口统计调用频次
MINUTE	分钟	以“1分钟（60秒）”为时间窗口统计调用频次

具体限流规则

开放平台采用多维度、多时间粒度的组合限流策略，任一维度/时间粒度触发上限均会判定为超限，具体规则如下：

限流维度	时间粒度	调用频次上限	说明
USER	秒	100次/秒	单个用户每秒最多可调用API 100次
USER	分钟	5000次/分钟	单个用户每分钟最多可调用API 5000次
APP	秒	20次/秒	单个应用每秒最多可调用API 20次
APP	分钟	1000次/分钟	单个应用每分钟最多可调用API 1000次
GLOBAL	秒	3000次/秒	开放平台全局每秒最多处理API调用3000次
GLOBAL	分钟	150000次/分钟	开放平台全局每分钟最多处理API调用150000次

注：限流规则遵循“就低不就高”原则，例如：单个用户1秒内调用101次，即使分钟级未到5000次上限，也会触发限流；单个应用1分钟内调用1001次，即使秒级未到20次上限，也会触发限流。

限流触发处理

1. 返回状态码：调用频次触发限流后，接口会立即返回状态码 60001（INTERFACE_RATE_LIMIT），具体信息如下：
   • 状态码：60001
   • 提示信息：Rate limit exceeded, please try again later（接口调用频率超限，请稍后重试）
   • 中文说明：接口调用频率超限，请稍后重试
2. 恢复机制：触发限流后，需等待当前时间窗口结束（如秒级限流需等待1秒，分钟级限流需等待剩余分钟时长），调用频次计数会重置，可恢复正常调用。

注意事项

1. 限流计数以API实际接收并处理请求为准，请求参数错误、认证失败等非业务处理请求仍会计入限流次数；
2. 建议开发者在调用端实现限流控制逻辑，根据本规则合理拆分请求（如批量请求拆分为多次小额请求），避免集中调用触发限流；
3. 若业务场景需要更高的调用频次上限，可联系开放平台运营人员申请调整限流阈值；
4. 限流规则可能根据平台服务容量动态调整，调整前会提前通过开放平台公告告知开发者。