# RATELIMIT.CHECK

> Check a request against a rate limiter for one key, and consume units if it is allowed.

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

```
RATELIMIT.CHECK name key [COST n]
```

- 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.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](https://docs.hotkv.com/commands/ratelimit-create/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)