Module Hub Beta

CL.THROTTLE

key max_burst count_per_period period [quantity]

`key` is an identifier to rate limit against. Examples might be:

  • A user account’s unique identifier.
  • The origin IP address of an incoming request.
  • A static string (e.g. global) to limit actions across the entire system.

For example:


CL.THROTTLE user123 15 30 60 1
▲ ▲ ▲ ▲ ▲
| | | | └───── apply 1 token (default if omitted)
| | └──┴─────── 30 tokens / 60 seconds
| └───────────── 15 max_burst
└─────────────────── key "user123"

This means that a single token (the 1 in the last parameter) should be applied against the rate limit of the key user123. 30 tokens on the key are allowed over a 60 second period with a maximum initial burst of 15 tokens. Rate limiting parameters are provided with every invocation so that limits can easily be reconfigured on the fly.

Return Value

Array reply, specifically the meaning of each array item is:

  1. Whether the action was limited:
    1. 0 indicates the action is allowed.
    2. 1 indicates that the action was limited/blocked.
  2. The total limit of the key (max_burst + 1). This is equivalent to the common `X-RateLimit-Limit` HTTP header./li>
  3. The remaining limit of the key. Equivalent to `X-RateLimit-Remaining`.
  4. The number of seconds until the user should retry, and always -1 if the action was allowed. Equivalent to `Retry-After`.
  5. The number of seconds until the limit will reset to its maximum capacity. Equivalent to `X-RateLimit-Reset`.

Examples

redis> CL.THROTTLE user123 15 30 60
1) (integer) 0
2) (integer) 16
3) (integer) 15
4) (integer) -1
5) (integer) 2

© 2017 Redis Labs, Inc. All rights reserved.