> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fabricgateway.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fabricgateway.ai/_mcp/server.

# Rate Limit plugin

> Reference for the Rate Limit plugin, which limits the number of requests in a time window.

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

|             |                                                       |
| ----------- | ----------------------------------------------------- |
| Protocols   | All                                                   |
| Scope kinds | `route` only. The control plane rejects other scopes. |
| Phase       | Request                                               |

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`** `string` — default: 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`** `integer` — required

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

---

**`window`** `integer` — default: 60

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

---

**`show_headers`** `boolean` — default: 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

```json
{
  "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 }
}
```

## Related guides

* [Set rate limits](/configure/access-and-limits/rate-limits)
* [Control traffic with plugins](/configure/plugins)