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.

GCRA.LIMIT

Last updated 
GCRA.LIMIT key period burst [count]
Group
Rate limiting
Complexity
O(1)
Arity
-4 (at least 4 words, counting the command name)
Flags
write, fast
Keys
first 1, last 1, step 1
HotKV Cloud
All plans
On-Premise
no license needed

GCRA.LIMIT decides whether a request identified by key is allowed under a limit of burst requests per period milliseconds, and records it if it is. The check and the update happen in one step, so concurrent clients cannot both pass on the same state.

The limit refills smoothly rather than in fixed windows: a client that has been idle can send up to burst requests at once, after which one more request is allowed every period / burst milliseconds. For example, a period of 60000 and a burst of 10 allows 10 requests straight away and then one every 6 seconds.

The key expires on its own once the limit has fully refilled. Use a dedicated key for each limited client or resource.

Arguments

Section titled “Arguments”
Argument Meaning
period The time window in milliseconds, from 1 to 1000000000000.
burst The number of requests allowed per period, a positive integer.
count How many requests this call stands for (default 1). A count above burst is always denied.

Return value

Section titled “Return value”

An array of five integers, the same in RESP2 and RESP3:

Element Meaning
1 0 if the request is allowed, 1 if it is denied.
2 The limit (burst).
3 Requests still available right now (0 when denied).
4 Milliseconds to wait before retrying, or -1 when allowed.
5 Milliseconds until the limit is fully refilled.

A denied request changes nothing.

Error replies:

  • ERR invalid period: must be a positive integer (milliseconds)
  • ERR invalid burst: must be a positive integer
  • ERR invalid count: must be a positive integer
  • WRONGTYPE if the key holds a value that is not a string, or a string that is not a number (so a limiter never overwrites a value of yours). The key is left as it is.

Examples

Section titled “Examples”
127.0.0.1:6379> GCRA.LIMIT ratelimit:user:42 60000 10
1) (integer) 0
2) (integer) 10
3) (integer) 9
4) (integer) -1
5) (integer) 6000
127.0.0.1:6379> GCRA.LIMIT ratelimit:user:42 60000 10
1) (integer) 0
2) (integer) 10
3) (integer) 8
4) (integer) -1
5) (integer) 12000
127.0.0.1:6379> GCRA.LIMIT ratelimit:user:42 60000 10 10
1) (integer) 1
2) (integer) 10
3) (integer) 0
4) (integer) 12000
5) (integer) 12000

The millisecond values depend on the time between calls.

Compatibility

Section titled “Compatibility”

HotKV-only command.

See also

Section titled “See also”

GCRA.RESET