In Cloudflare Workers, how does the rate limiting binding enforce a per-user limit, and how do its periods and counters differ from a rate limiting rule's?
answer
- a limit called from code
- ratelimits with a simple block
- only two allowed periods
- success false, you answer
- local to each location
basics
~20 sA ratelimits binding sets a namespace_id, a limit and a 10 or 60 second period; the Worker calls limit({ key }) with, say, the account ID and answers with its own 429 when success is false. Counters are per location and approximate.
solid answer
~50 sSince the binding went GA in September 2025, a Worker declares it under `ratelimits` with a `name`, a string `namespace_id` and `simple: { limit, period }`, where `period` must be `10` or `60`. In code, `await env.RESET_LIMITER.limit({ key })` resolves to `{ success }`; the key is any string, ideally an account, user or tenant ID plus the route, not an IP that many users share. On `success: false` the Worker returns its own response, typically a JSON `429`. Counters are local to each Cloudflare location, cached on the machine and synced in the background, so the call adds almost no latency but is permissive and eventually consistent. Bindings sharing a `namespace_id` share counters, even across Workers. Unlike a rate limiting rule, it runs only where code calls it, so a flood still invokes the Worker.
code
json · 15 lines{
"name": "login-api",
"main": "src/index.js",
"compatibility_date": "2026-10-01",
"ratelimits": [
{
"name": "RESET_LIMITER",
"namespace_id": "2001",
"simple": {
"limit": 5,
"period": 60
}
}
]
}go deeper
Know the shape: a ratelimits entry with name, namespace_id and simple limit and period, and a limit({ key }) call that returns success.
Explain the 10 or 60 second periods, per-location counters, eventual consistency, shared namespaces, and why the key should be a user or account rather than an IP.
Show where the binding fits behind a rate limiting rule, how to normalise keys so one identity shares a counter, and how to monitor 429s through Workers Logs.
Decide which limits live in code and which at the edge, and when an exact per-customer quota needs a strongly consistent store instead of this binding.
## What the binding is for A WAF rate limiting rule acts before a request reaches your code, keyed on what Cloudflare can read from the request: an IP, and on higher plans a header, cookie or body field. Some limits need what only your code knows: the account a password-reset request names after the body is parsed, the customer tier behind an API key, or a limit on one expensive branch of a handler. The **Workers rate limiting binding** gives a Worker the same counting infrastructure that serves rate limiting rules, called from code. Since the binding went generally available in September 2025, it is declared under `ratelimits` in the Wrangler configuration; earlier deployments used an `unsafe` binding, which still works so existing Workers can move over. ## Declaring it Each entry in `ratelimits` has three settings: - `name`: the binding name the Worker reads from `env`. - `namespace_id`: a positive integer, written as a string, that identifies the counter namespace within your Cloudflare account. - `simple`: the only supported configuration type, with `limit` (calls allowed per period) and `period` in seconds, which must be **10 or 60**. Wrangler rejects any other value when it reads the configuration. ```json { "ratelimits": [ { "name": "RESET_LIMITER", "namespace_id": "2001", "simple": { "limit": 5, "period": 60 } } ] } ``` ## Calling it `env.RESET_LIMITER.limit({ key })` takes one object with a string `key` and resolves to `{ success }`. When `success` is `false` the key is over its limit, and the Worker decides what to send back; the binding returns no response of its own. A good key names the actor and, where it matters, the resource: `reset:<account>`, `api:<customerId>:/v1/search`. Normalise it (trim, lowercase an email address) so trivial variations of one identity share a counter. Cloudflare's guidance is to avoid IP addresses and locations as keys, since many users share them on mobile networks and behind proxies. A per-account key on the password-reset path limits, in each location, how often one inbox can be flooded, whichever addresses the requests come from. Call `limit()` after cheap checks such as parsing the body, and before the expensive or abusable work it protects. ## How it counts 1. Counters are **local to the Cloudflare location** the Worker runs in. A key has a separate limit in each location, so a client whose requests land in two cities can use the limit twice. 2. Counters are cached on the machine running the Worker and synchronised in the background with a store inside the location. `await limit()` does not wait on a network round trip, so it adds no meaningful latency. 3. The result is **permissive and eventually consistent**. Requests arriving together on one key may all pass briefly before the count catches up, and the API is not meant for accurate accounting such as billing. 4. Bindings that share a `namespace_id` share counters for the same key, even across different Workers in the account. Give each limit its own namespace unless sharing is the point. ## How it differs from a rate limiting rule | | Rate limiting rule | Workers rate limiting binding | |---|---|---| | Where it runs | Before the Worker or origin, in the `http_ratelimit` phase | Wherever the code calls `limit()` | | What the key can be | Characteristics allowed by the plan | Any string the code builds | | Periods | From 10 s up to an hour or more, by plan | 10 or 60 s only | | What the client sees | The rule's action and response | Whatever the Worker returns | | Where you watch it | Security events | Workers Logs or your own data points | Because the binding runs inside the Worker, each limited request is still an invocation. A flood that should never reach code belongs to a rate limiting rule in front; the binding is the second, finer layer behind it. ## Watching it - Rate limiting bindings do not appear in the Cloudflare dashboard, so their effect has to be observed through the Worker. - Workers Logs and Traces show the `429` responses the Worker returns when `success` is `false`. - For trends over time, write a data point to Workers Analytics Engine each time a key is limited, tagged with the route and tier, and chart it.
- Why can a client get more than the configured limit through a Workers rate limiting binding?Counters are local to each Cloudflare location, so a key gets its limit separately in every location its requests land in. Within one location, each isolate checks a locally cached count that syncs in the background, so a burst on one key can pass briefly before the count catches up. The binding is meant for abuse control, not exact accounting.
- When would you use the binding instead of a WAF rate limiting rule?When the key exists only after your code runs, such as an account named in a parsed body or a customer tier looked up from an API key; when different tiers need different limits; or when only one branch of a handler is expensive. Keep a rule in front for floods, because the binding runs inside the Worker and every limited request is still an invocation.
- The binding's period can be any number of seconds, like a rule's period.
- The binding answers the client with 429 by itself when the key is over its limit.
- Each binding keeps private counters even when two share a namespace_id.
- The client IP from CF-Connecting-IP is the recommended key for the binding.
- limit() waits on a global counter, so it adds a cross-region round trip.
Assumes Cloudflare as of 2026-10-10: the ratelimits binding has been generally available since September 2025; before that it was declared as an unsafe binding.