Skip to navigation

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

ProtocolsAll
Scope kindsroute only. The control plane rejects other scopes.
PhaseRequest

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.

Configuration

Unknown fields are rejected.

key_by
stringDefaults to consumer

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.

limit
integerRequired

The number of requests allowed in the window, from 1 to 1,000,000,000. The console labels this Limit.

window
integerDefaults to 60

The window length in seconds, from 1 to 31,536,000 (one year). The console labels this Window (seconds).

show_headers
booleanDefaults to false

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. Set it with Edit as JSON, and keep editing that instance as JSON, because the form can’t save an instance that has it.

Changing limit or window keeps the counter. Renaming the route resets it.

Example

{
"name": "orders-per-consumer",
"plugin_id": "rate-limit",
"scope": { "kind": "route", "name": "orders-api" },
"config": { "key_by": "consumer", "limit": 100, "window": 60, "show_headers": true }
}