Runtime APIs
Rate Limiting
Use the Workers Rate Limiting binding on OpenOrange, where each namespace_id is one Rivet Actor with an exact fixed-window counter.
Runs on Internal Rivet Actor per namespace_id with an exact fixed-window counter
- Works
limit()with yoursimplelimit and period, per-call overrides, and the same option checks aswrangler dev- Differs
- One exact counter for each
namespace_id, where Cloudflare counts per location and approximately. Each call is a round trip to a Rivet Actor. - Missing
- Nothing
- Migration
- Not needed Counters start fresh in each window.
- Configure
ratelimitsunsafe.bindings- Scales by
- Namespace
- Checks
- 1 pass
Rate Limiting caps how often each client can call your Worker. Your code and
wrangler.jsonc run on Orange as they are.
Quickstart
This limits each client to 100 requests a minute.
-
Bind the rate limiter
Add a
ratelimitsentry towrangler.jsonc.periodis in seconds, and it is 10 or 60.{ "name": "my-api", "main": "src/index.ts", "compatibility_date": "2026-09-03", "ratelimits": [ { "name": "MY_RATE_LIMITER", "namespace_id": "1001", "simple": { "limit": 100, "period": 60 } } ] } -
Call limit() for each request
Pick a key for each client, such as an IP address or a user ID.
limit()resolves to{ success: false }once the key has used its limit in this window.export default { async fetch(request, env): Promise<Response> { const key = request.headers.get("cf-connecting-ip") ?? "anonymous"; const { success } = await env.MY_RATE_LIMITER.limit({ key }); if (!success) { return new Response("Too Many Requests", { status: 429 }); } return new Response("ok"); }, } satisfies ExportedHandler<Env>; -
Run it
orange devserves the Worker on port 8787.orange devSend 101 requests inside one clock minute. The first 100 get
200, and the 101st gets429.for i in $(seq 1 101); do curl -s -o /dev/null -w '%{http_code}\n' localhost:8787/; done
How it works
- Each
namespace_idis one Rivet Actor with its own SQLite database. It holds the counter of every key, and the counters survive a restart oforange dev. - Each window starts on a multiple of the period, so a 60-second window starts at each full minute. The counter starts again in the next window.
- A call adds one to its key’s counter until it reaches
limit. Calls that getsuccess: falsedo not count.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
| Feature | Status | Notes |
|---|---|---|
limit({ key }) | Supported | Resolves to { success }. |
limit and period overrides in one call | Supported | As in wrangler dev. The period must still be 10 or 60. |
| Option errors | Supported | The same error text as wrangler dev, such as bad rate limit options: [window]. |
Two differences reach most projects:
- Orange never lets a call over the limit through. Cloudflare’s count is
approximate, so it can allow a few more calls than
limit. Traffic that went slightly over the limit on Cloudflare getssuccess: falseon Orange. - A client can choose its own IP key. Orange sets
cf-connecting-ipfrom the connection only when the request has no such header, aswrangler devdoes. Key a limit on it only behind a proxy that sets the header.
Limits
| What | Limit | What happens over it |
|---|---|---|
| Calls for one key in one window | The binding’s limit, or the limit of the call | limit() resolves to { success: false } until the next window. |
period | 10 or 60 seconds | In wrangler.jsonc, orange dev stops with an error. In a call, limit() rejects with unsupported period: <period>. |
What Orange reads
Orange reads the binding as wrangler dev does:
In wrangler.jsonc | On Orange |
|---|---|
ratelimits | Supported, with Wrangler’s checks. |
unsafe.bindings with "type": "ratelimit" | The same fields, with the same checks. |
namespace_id | Names the counter. Bindings with the same namespace_id share counters, also across the Workers of one orange dev session. |
Configuration edge cases
orange devstops with an error when a rate limiter’speriodis not 10 or 60, or itslimitis not a number.ratelimitsgoes through Wrangler’s own validation, so its errors are Wrangler’s, for example"simple.period" must be either 10 or 60 but got 30.- Wrangler passes
unsafe.bindingsthrough unchecked, so Orange checks that form like Miniflare’s binding schema. Its errors name the binding:Rate Limiting binding <NAME> must have a simple configuration objectRate Limiting binding <NAME> simple.limit must be a number but got "5"Rate Limiting binding <NAME> simple.period must be either 10 or 60 but got 30<NAME>.namespace_id must be a non-empty string
- Any number loads as
limit, including0, which rejects every call. - Two bindings with the same
namespace_idshare the counter of a key only when they use the same period. The counter is per key and period, and each call applies its own binding’slimit. For example, a login limiter and a password-reset limiter with onenamespace_idand one period spend one budget for each account.
limit() options
limit() checks its options as Miniflare’s client does, with the same error
text. Each failed check rejects the call with an Error:
| Call | Error message |
|---|---|
| Options that are not an object | invalid rate limit options |
An option other than key, limit, and period | bad rate limit options: [window] |
A key that is not a string | invalid key: 1 |
A limit that is not a number | limit must be a number: <value> |
A period that is not a number | period must be a number: <value> |
A period other than 10 or 60 | unsupported period: 30 |
- Only an absent or
undefinedoption falls back to the binding’ssimplevalue. - A call without
keycounts under the empty string. - Cloudflare’s public types list only
key. A TypeScript Worker that passeslimitorperiodneeds its own type for the options. - When the actor answers with an error, the call rejects with
Rate limit call failed: <status> <body>.
The counter
- The counter is a fixed window, as in
wrangler dev. - Each key and period has one counter.
- A client can use its whole limit at the end of one window and again at the start of the next.
- Each call reads and updates its counter in one SQLite transaction, so calls
that overlap never get more than
limitthrough. - The actor’s class is the internal
openorange:ratelimit. RivetKit shows it asRate Limiting (Orange). The binding table oforange devshows each binding as aRate Limiteron aRivet Actor. - The window is
floor(now / period). Each row of theopenorange_ratelimit_bucketstable holds a key, a period, its window, and its count. When a call finds no row for the current window, the actor also deletes every row of an earlier window of that period. - Counters persist in the local Engine state under
.open-orange/rivetkit/. - The current window ends in
period - (seconds since the epoch % period)seconds, which a Worker can send asRetry-After. On Cloudflare, treat the value as a hint.
cf-connecting-ip
orange dev and orange serve both fill in cf-connecting-ip from the
client’s socket address, as Miniflare does. Locally, send the header yourself
to act as another client.
Deviations
These add to the differences under Compatibility.
- Cloudflare’s count is eventually consistent across its locations.
- Orange’s windows start on wall-clock multiples of the period. Cloudflare does not document where its windows start.
Conformance
tests/bindings/bindings.test.tsruns a realorange devwith both configuration forms. It covers the limit per key, separate keys and namespaces, a namespace shared by two bindings, the next window, 60 overlapping calls on two keys, the option errors, and counts that survive a restart.src/config/load-wrangler.test.tscovers both configuration forms and their errors.- The runnable example
tests/fixtures/examples/rate-limitinglayers a per-IP limit, a per-user limit with a higher limit for pro users, and login throttling with429andRetry-After.tests/examples/runnable-examples.test.tsruns it end to end.
Recorded results
Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.
Rate Limiting
| Check | Status | Results |
|---|---|---|
| Rate Limiting | Works |
|