Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

RATELIMIT.CREATE

Last updated 
RATELIMIT.CREATE name limit window_ms [ALGO sliding_window | token_bucket | leaky_bucket] [REFILL rate] [DRAIN rate]
Group
Rate limiting
Complexity
O(1)
Arity
-4 (at least 4 words, counting the command name)
Flags
write, slow
Keys
first 1, last 1, step 1
HotKV Cloud
Performance and Scale
On-Premise
requires the rate-limiting license feature

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.CREATE creates a limiter that allows limit units per window_ms milliseconds for each key. Both must be positive integers.

Options

Section titled “Options”
Option Effect
ALGO sliding_window Counts units over a moving window of window_ms. The default.
ALGO token_bucket Each key has a bucket of limit tokens, full at first, refilled continuously. Allows bursts up to limit.
ALGO leaky_bucket Each key has a bucket that fills with each request and drains at a steady rate; a request is refused if it would overflow limit.
REFILL rate Token bucket refill rate, in tokens per second. Default limit divided by the window in seconds.
DRAIN rate Leaky bucket drain rate, in units per second. Default limit divided by the window in seconds.

Option and algorithm names are case-insensitive.

Return value

Section titled “Return value”
Case RESP2 RESP3
Limiter created Simple string OK Same

Errors:

  • ERR invalid limit (must be > 0) or ERR invalid window_ms (must be > 0) if either is not a positive integer.
  • ERR unknown algo: use sliding_window|token_bucket|leaky_bucket for any other algorithm.
  • ERR invalid REFILL rate or ERR invalid DRAIN rate if the rate is not a positive number.
  • ERR limiter already exists or limit reached if the limiter exists, or the server already holds its maximum number of limiters (max_limiters under [ratelimit]).
  • ERR wrong number of arguments for 'ratelimit.create' 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

Section titled “Examples”
127.0.0.1:6379> RATELIMIT.CREATE api 100 60000
OK
127.0.0.1:6379> RATELIMIT.CREATE burst 10 1000 ALGO token_bucket
OK
127.0.0.1:6379> RATELIMIT.CREATE smooth 50 1000 ALGO leaky_bucket DRAIN 25
OK

Compatibility

Section titled “Compatibility”

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

See also

Section titled “See also”

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