# RATELIMIT.CREATE

> Create a named rate limiter with a limit, a window and an algorithm.

URL: https://docs.hotkv.com/commands/ratelimit-create/

```
RATELIMIT.CREATE name limit window_ms [ALGO sliding_window | token_bucket | leaky_bucket] [REFILL rate] [DRAIN rate]
```

- Group: Rate limiting
- Complexity: O(1)
- HotKV Cloud: Performance and Scale plans
- 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

| 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

| 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

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

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

## See also

[RATELIMIT.CHECK](https://docs.hotkv.com/commands/ratelimit-check/index.md), [RATELIMIT.PEEK](https://docs.hotkv.com/commands/ratelimit-peek/index.md), [RATELIMIT.RESET](https://docs.hotkv.com/commands/ratelimit-reset/index.md), [RATELIMIT.STATS](https://docs.hotkv.com/commands/ratelimit-stats/index.md), [RATELIMIT.DROP](https://docs.hotkv.com/commands/ratelimit-drop/index.md), [RATELIMIT.LIST](https://docs.hotkv.com/commands/ratelimit-list/index.md), [AI features guide](https://docs.hotkv.com/ai-features/index.md)