Rate Limit plugin
The Rate Limit plugin counts requests in a time window and refuses a request with 429 Too Many Requests when the caller’s limit is used up. You choose what the counter is keyed by: the consumer, the API key, or the whole route.
Where it runs
A route can carry several Rate Limit instances with different key_by values, and all of them run. Two enabled instances on one route with the same key_by are rejected, because they would share one counter.
Set up the plugin
Add a Rate Limit instance to a route in the console.
Prerequisites
- A route to limit. Rate Limit attaches to routes only.
- For Consumer, an authentication plugin on the route, such as Key Auth, so each request has a caller. For Credential, Key Auth on the route.
Steps
- In the console sidebar, select Plugins, then open the All tab.
- Find rate-limit and select Use.
- In Instance name, enter a name, for example
orders-per-consumer. - In Routes, select the route to limit. If you select several routes, the console creates one instance for each and Instance name becomes Base name.
- Under Configuration, in Count by, select Consumer (default), Credential, or Global.
- In Limit, enter the number of requests allowed in the window. The form starts at
100. - In Window (seconds), enter the window length. Leave it empty to use 60 seconds.
- Optional: expand Match conditions (optional) to limit the plugin to a path prefix, methods, a consumer, or a consumer group.
- Make sure Enabled is selected, then select Create instance.
Verify it works
Set Limit to 2, then send three requests in a row to the route with the same credential:
The first two return the upstream’s status. The third returns 429 Too Many Requests. In Traces, select the refused request’s span. Its fabric.error.reason attribute is rate_limited.
Fix common problems
503on every request. The request has no value for Count by. For Consumer or Credential, add the authentication plugin that identifies the caller, or switch to Global. A503can also mean the limiter is unavailable, and the trace shows the error reasonrate_limit_unavailable.- The console refuses to save with a scope or duplicate error. Rate Limit accepts route scope only, and two enabled instances on one route can’t share a Count by value. Change the scope or the Count by value.
Configuration
Unknown fields are rejected.
What each counter belongs to. consumer keeps one counter per authenticated caller and requires authentication on the route. A request with no value for the chosen key is refused with 503. credential keeps one counter per API key, filled only when Key Auth identifies the caller. global keeps one counter for every request on the route. The console labels this Count by.
The number of requests allowed in the window, from 1 to 1,000,000,000. The console labels this Limit.
The window length in seconds, from 1 to 31,536,000 (one year). The console labels this Window (seconds).
Adds rate limit headers to responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit, and RateLimit-Policy. A refused request also gets Retry-After. Reset values are seconds until the window resets. The console form doesn’t show this field, and the console has no JSON editor for this plugin. Set it through the admin API. Editing the instance in the console afterward keeps the value.
Changing limit or window keeps the counter. Renaming the route resets it.

