Rate Limit

This module provides support for request rate limits.

Example configuration

The following configuration will allow:

  • 5000 requests per hour from the consumer foo.
  • 1 request per second from the consumer bar.
  • 200 requests per minute or 10 requests per second from any other consumer or client.
{
    "name": "example",
    "host": "example.com",
    "path": "/*",
    "modules": [
        {
            "name": "rate-limit",
            "order": 0,
            "consumers": {
                "foo": {
                    "hour": 5000
                },
                "bar": {
                    "second": 1
                }
            },
            "default": {
                "minute": 200,
                "second": 10
            }
        }
    ]
}

Configuration attributes

Attribute Required Type Default Description
hour No Int Number of requests allowed per hour.
minute No Int Number of requests allowed per minute.
second No Int Number of requests allowed per second.
limit-by No String consumer id ip Whitespace separated string containing keys to use for rate limits. This is used to select which keys to use for limits, and also their priority (from left to right). The first match is used. The reserved keywords are: consumer is the username of the consumer, id is the session id as set by one of the authentication modules and ip is the client IP.

Limit-by explained

The limit-by configuration attribute is used to specify how requests are counted for the rate limits. Its value is a whitespace separated string containing keywords. There are some reserved keywords with special meaning:

Keyword Description
consumer The consumer name will be used if the request is authenticated using one of the authentication modules.
id The session id will be used if the request has a session from one of the authentication modules.
ip The client IP will be used. Keep in mind that the client IP might not be the IP of the end user, depending on the environment.

The default value of limit-by will count incoming requests like this:

  1. If the request is authenticated using one of the auth modules, the rate limit will apply to the consumer.
  2. If the request has a session id, the rate limit will apply to the session id.
  3. The rate limit will apply to the source IP address of the policy request.

Values that do not match any reserved keywords will be matched with the request headers. An example:

{
    "name": "example",
    "host": "example.com",
    "path": "/*",
    "modules": [
        {
            "name": "rate-limit",
            "order": 0,
            "default": {
                "minute": 100,
            },
            "general": {
                "limit-by": "foo ip" 
            }
        }
    ]
}

The configuration above will count incoming requests like this:

  1. If the request is contains the request header foo, the rate limit will count based on the value of foo.
  2. If the request does not contain the request header foo, the rate limit will count based on the client IP.

If the client request does not match any of the keywords specified in limit-by, the request will not be counted for any rate limits.

Response status

Status Description
200 Quota not reached.
429 Too many requests.

Response headers

If multiple rate limits apply, the various limits will be separated in the response headers by whitespace.

Header Description
X-RateLimit-Limit The number of requests allowed per period.
X-RateLimit-Remaining The number of requests remaining in the limits.
X-RateLimit-Reset The number of seconds remaining of the periods before the limits are reset.