跳转到内容

ecentic API 速率限制。

每个公开响应都会携带当前窗口的实时状态,因此智能体可以自行控制请求节奏,而不是等被拒绝后才知道达到限制。

实时响应头 · 429 时返回 Retry-After · 按密钥划分窗口

01

策略

公共接口使用固定窗口,并按凭证计数。

public

所有 /api/v1 端点

120请求

每 60 秒

news

/api/v1/news

30请求

每 60 秒

news-resolve

/api/v1/news?resolve=true

6请求

每 60 秒

携带 bearer key 的请求会计入该密钥的额度;其他请求则按客户端 IP 计数,因此单个高频智能体无法耗尽共享地址的配额。

窗口为固定窗口,而非滑动窗口:它会在时钟边界重置,响应头中的 reset 值表示距离下一个重置边界还剩多少秒。

API 强制执行的策略
02

响应头

两种拼写都会发送。读取客户端已经支持的即可。

RateLimit-Policy 始终存在,因为无论请求是否被计数,策略本身都成立。实时计数器仅在确实存在计数时才会发送——如果某个环境无法访问计数器,就会省略这些字段,而不是声称存在未实际测量的配额。

选择一个响应头查看其含义。这些值仅用于演示响应,不是实时计数器。

响应头示例

含义: 当前生效的策略:配额和窗口时长(秒)。

同一时间窗口,两种表示方式

在此示例中,两种响应头格式描述的是同一个时间窗口。

剩余请求数
118
r=118 · RateLimit-Remaining
距离重置的秒数
42
t=42 · RateLimit-Reset
03

超出限制时

429 与其他失败一样,也是类型化的 problem。

响应为 application/problem+json,代码为 rate-limited,并会与速率限制响应头一起返回 Retry-After。请按其中指定的秒数退避,而不是立即重试——在同一窗口内重试仍会被计数,并再次被拒绝。

示例:429 响应