# GCRA.LIMIT

> Check and consume a rate limit in one atomic step, using the generic cell rate algorithm.

URL: https://docs.hotkv.com/commands/gcra-limit/

```
GCRA.LIMIT key period burst [count]
```

- Group: Rate limiting
- Complexity: O(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

| 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

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

```
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

HotKV-only command.

## See also

[GCRA.RESET](https://docs.hotkv.com/commands/gcra-reset/index.md)