Document updated on Oct 26, 2021

Service rate limit (stateless)

The service rate limit feature allows you to set the maximum requests per second a user or group of users can do to KrakenD and works analogously to the endpoint rate limit. There are two different strategies to set limits that you can use, simultaneously or individually:

• Service rate-limit: Defines the rate-limit that all users of your API can do together, sharing the same counter. For instance, you might want to limit the interaction from users to KrakenD to 10,000 requests/second to avoid a possible DDoS propagating to your backend services.
• Client rate-limit: Rate-limits what an individual user can do against all endpoints. For instance, a personal JWT token can make 100 requests/second to the API.

Both types keep in-memory an updated Token Bucket expressing the remaining requests for a user or group of users.

For additional types of rate-limiting see the Traffic management overview.

Service rate-limiting (max_rate)

The service rate limit acts on the number of simultaneous transactions KrakenD allows to process. This type of limit protects the service from all customers. In addition, these limits mitigate abusive actions such as rapidly writing content, aggressive polling, or excessive API calls.

It consumes an insignificant amount of memory as it only needs one counter for the whole system.

When the users connected to an endpoint together exceed the max_rate, KrakenD starts to reject connections with a status code 503 Service Unavailable and enables a Spike Arrest policy

Service client rate-limiting (client_max_rate)

The client or user rate limit applies to an individual user to all endpoints. Each endpoint can additionally have sub-limit rates, but all users are subject to the same rate.

The client_max_rate tracks one counter per different client.

When a single user connected to an endpoint exceeds their client_max_rate, KrakenD starts to reject connections with a status code 429 Too Many Requests and enables a Spike Arrest policy

Service rate-limiting configuration

The configuration allows you to use both types of rate limits at the same time:

{
    "version": 3,
    "extra_config": {
      "qos/ratelimit/service": {
          "max_rate": 50,
          "client_max_rate": 5,
          "strategy": "ip"
        }
    }
}

A note on strategies:

• "strategy": "ip" When the restrictions apply to the client’s IP, and every IP is considered to be a different user. Optionally a key can be used to extract the IP from a custom header:
  • E.g, set "key": "X-Original-Forwarded-For" to extract the IP from a header containing a list of space-separated IPs (will take the first one).
• "strategy": "header" When the criteria for identifying a user comes from the value of a key inside the header. With this strategy, the key must also be present.
  • E.g., set "key": "X-TOKEN" to use the X-TOKEN header as the unique user identifier.