RATELIMIT.CHECK

Named rate limiters apply one policy (a limit, a window and an algorithm) separately to every key you check against them, such as a user id, an API key or an IP address. RATELIMIT.CHECK asks whether a request costing COST units (default 1) fits within the limit for key. If it does, the units are consumed. A refused request consumes nothing.

Options

Option	Effect
COST n	Units this request uses, a positive integer. Default 1.

Return value

Case	RESP2	RESP3
Always	Array of five integers (below)	Same

Position	Type	Meaning
1	Integer	1 if allowed, 0 if not.
2	Integer	Units still available after this request (0 when not allowed).
3	Integer	When not allowed, milliseconds until the request would fit; otherwise 0.
4	Integer	The limiter’s limit.
5	Integer	Units in use before this request.

For a limiter that does not exist, every element is 0.

Errors:

• ERR invalid COST if COST is not a positive integer.
• ERR wrong number of arguments for 'ratelimit.check' command if the argument count is wrong.
• NOLICENSE rate-limiting requires a HotKV license. Contact sales@hotkv.com if your license does not include the rate-limiting feature.

Examples

127.0.0.1:6379> RATELIMIT.CREATE api 100 60000
OK
127.0.0.1:6379> RATELIMIT.CHECK api user:1
1) (integer) 1
2) (integer) 99
3) (integer) 0
4) (integer) 100
5) (integer) 0
127.0.0.1:6379> RATELIMIT.CHECK api user:1 COST 99
1) (integer) 1
2) (integer) 0
3) (integer) 0
4) (integer) 100
5) (integer) 1
127.0.0.1:6379> RATELIMIT.CHECK api user:1
1) (integer) 0
2) (integer) 0
3) (integer) 600
4) (integer) 100
5) (integer) 100

Compatibility

HotKV-only command. Redis and Valkey have no equivalent.

See also

RATELIMIT.CREATE, RATELIMIT.PEEK, RATELIMIT.RESET, RATELIMIT.STATS, RATELIMIT.DROP, RATELIMIT.LIST, AI features guide