Response Rate Limiting

This plugin allows you to impose rate limits based on custom response headers returned by the upstream service. You can arbitrarily set as many rate limiting objects (or quotas) as you want and instruct Kong Gateway to increase or decrease them by any number of units.

For example, if there are different costs associated with specific upstream services, they can be returned as headers to Kong Gateway, and Kong Gateway will increment the rate limit counters based on these costs.

Each custom rate limiting object can limit the inbound requests in number of seconds, minutes, hours, days, months, or years.

If the underlying Gateway Service or Route has no authentication layer, the client IP address is used for identifying clients. Otherwise, the Consumer is used if an authentication plugin has been configured.

The Response Rate Limiting plugin supports three rate limiting strategies: local, cluster, and redis. This is controlled by the config.policy parameter.

If limiting by IP address, it’s important to understand how Kong Gateway determines the IP address of an incoming request.

The IP address is extracted from the request headers sent to Kong Gateway by downstream clients. Typically, these headers are named X-Real-IP or X-Forwarded-For.

By default, Kong Gateway uses the header name X-Real-IP to identify the client’s IP address. If your environment requires a different header, you can specify this by setting the real_ip_header Nginx property. Depending on your network setup, you may also need to configure the trusted_ips Nginx property to include the load balancer IP address. This ensures that Kong Gateway correctly interprets the client’s IP address, even when the request passes through multiple network layers.

After adding the plugin, you can increment the configured limits by adding the following response header:

Header-Name: Limit=Value [,Limit=Value]

You can change the default header name using config.header_name.

You can optionally increment more than one limit with comma-separated entries. The header is removed before returning the response to the original client.

When the Response Rate Limiting plugin is enabled, Kong Gateway sends additional headers back to the client, indicating how many units are still available and how many are allowed total.

For example, if you created a limit called Videos with a per-minute limit:

X-RateLimit-Limit-Videos-Minute: 10
X-RateLimit-Remaining-Videos-Minute: 9

If more than one limit value is set, it returns a combination of all the time limits:

X-RateLimit-Limit-Videos-Second: 5
X-RateLimit-Remaining-Videos-Second: 5
X-RateLimit-Limit-Videos-Minute: 10
X-RateLimit-Remaining-Videos-Minute: 10

If any of the configured limits configured is reached, the plugin returns an HTTP/1.1 429 (Too Many Requests) status code and an empty response body.

Upstream headers

The plugin appends usage headers for each limit before proxying the request to the upstream service, so that you can properly refuse to process the request if there are no more limits remaining. The headers are in the form of X-RateLimit-Remaining-LIMIT_NAME, for example:

X-RateLimit-Remaining-Videos: 3
X-RateLimit-Remaining-Images: 0