公开 API
每个 API 密钥按套餐获得限额，表现良好的客户端可以突发，其余的则收到精确的 Retry-After。
核心数据API
限流
原子化的服务器端限流。一条命令完成 GCRA，或使用滑动窗口、令牌桶或漏桶的命名限流器。无需 Lua。
- 条原子命令对应每个请求
- 1
- 种算法
- 4
- 个 Lua 脚本
- 0
步骤 1 / 5
允许
用户 42 每分钟 10 个请求。回复中包含是否允许、限额以及剩余次数。
示例会话playing
# 允许
hotkv> GCRA.LIMIT ratelimit:user:42 60000 10
1) (integer) 0
2) (integer) 10
3) (integer) 9
4) (integer) -1
5) (integer) 6000
使用真实 HotKV 命令和示例回复的动画演示。点击任意步骤即可跳转。 命令和回复保持英文，与您在 HotKV 中输入和看到的完全一致。
问题所在
没有限流的 API，离一次故障只差一个行为异常的客户端。在应用代码中做检查意味着一次读取、一次计算和一次写入，并发请求会从它们之间的缝隙中溜过去。许多团队最后不得不维护一个 Lua 脚本，只为了让它变成原子操作。
HotKV 如何解决
GCRA.LIMIT 在一步之内完成判定和记录，并发的客户端不可能基于同一个状态同时通过，而且额度平滑恢复，不会在窗口边界突然重置。对于按名称管理的限额，RATELIMIT.CREATE 可以创建滑动窗口、令牌桶或漏桶限流器，并统计其允许和拒绝的请求。
逐步演示
逐条命令，看看发生了什么
- 01
允许
用户 42 每分钟 10 个请求。回复中包含是否允许、限额以及剩余次数。
GCRA.LIMIT ratelimit:user:42 60000 10 - 02
机器人的一波突发
爬虫用完了它的突发额度，随后被告知需要等待多久。被拒绝的请求不会改变任何状态。
GCRA.LIMIT ratelimit:bot:7 60000 10 - 03
按套餐的命名限流器
免费套餐的客户在滑动窗口下每分钟 100 个请求。
RATELIMIT.CREATE free_plan 100 60000 ALGO sliding_window - 04
加权请求
导出端点消耗 20 个单位，因此会用掉更多额度。
RATELIMIT.CHECK free_plan customer:881 COST 20 - 05
查看限流器做了什么
设置、被跟踪的键，以及允许和拒绝请求的总数。
RATELIMIT.STATS free_plan
适用场景
真实场景
登录与注册表单
按 IP 和按账户限制尝试次数，以减缓撞库攻击。
出站调用
对合作方 API 或 LLM 服务商的调用，在整个集群的所有 worker 之间都保持在其配额以内。
内置功能
您将获得
一条命令完成 GCRA
支持突发的平滑恢复，原子化的检查与更新，拒绝时给出重试时间。
GCRA.LIMITGCRA.RESET命名限流器
滑动窗口、令牌桶或漏桶，创建一次，按键检查。
RATELIMIT.CREATERATELIMIT.CHECK加权请求
开销大的调用可以计为多个请求。GCRA.LIMIT 接收一个数量，RATELIMIT.CHECK 接收一个 COST。
COST统计
每个限流器允许和拒绝的总数。
RATELIMIT.STATS常见问题
限流需要 Lua 脚本吗？
不需要。GCRA.LIMIT 和 RATELIMIT.CHECK 都以一条原子命令完成整个检查。
我该用哪一个？
GCRA.LIMIT 无需任何设置，所有套餐均可使用。RATELIMIT.* 命名限流器增加了算法选择和统计，包含在 Performance 和 Scale 套餐中。
被拒绝的请求有什么代价？
没有。被拒绝的 GCRA 调用不会改变限流器，因此重试的客户端不会受到进一步惩罚。