Skip to content
Runtime APIs / Rate Limiting

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.

Drop-in

Runs on Internal Rivet Actor per namespace_id with an exact fixed-window counter

Works
limit() with your simple limit and period, per-call overrides, and the same option checks as wrangler 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.

  1. Bind the rate limiter

    Add a ratelimits entry to wrangler.jsonc. period is 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 }
        }
      ]
    }
  2. 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>;
  3. Run it

    orange dev serves the Worker on port 8787.

    orange dev

    Send 101 requests inside one clock minute. The first 100 get 200, and the 101st gets 429.

    for i in $(seq 1 101); do curl -s -o /dev/null -w '%{http_code}\n' localhost:8787/; done

How it works

  • Each namespace_id is one Rivet Actor with its own SQLite database. It holds the counter of every key, and the counters survive a restart of orange 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 get success: false do 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

FeatureStatusNotes
limit({ key })SupportedResolves to { success }.
limit and period overrides in one callSupportedAs in wrangler dev. The period must still be 10 or 60.
Option errorsSupportedThe 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 gets success: false on Orange.
  • A client can choose its own IP key. Orange sets cf-connecting-ip from the connection only when the request has no such header, as wrangler dev does. Key a limit on it only behind a proxy that sets the header.

Limits

WhatLimitWhat happens over it
Calls for one key in one windowThe binding’s limit, or the limit of the calllimit() resolves to { success: false } until the next window.
period10 or 60 secondsIn 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.jsoncOn Orange
ratelimitsSupported, with Wrangler’s checks.
unsafe.bindings with "type": "ratelimit"The same fields, with the same checks.
namespace_idNames the counter. Bindings with the same namespace_id share counters, also across the Workers of one orange dev session.

Configuration edge cases

  • orange dev stops with an error when a rate limiter’s period is not 10 or 60, or its limit is not a number.
  • ratelimits goes 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.bindings through 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 object
    • Rate 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, including 0, which rejects every call.
  • Two bindings with the same namespace_id share 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’s limit. For example, a login limiter and a password-reset limiter with one namespace_id and 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:

CallError message
Options that are not an objectinvalid rate limit options
An option other than key, limit, and periodbad rate limit options: [window]
A key that is not a stringinvalid key: 1
A limit that is not a numberlimit must be a number: <value>
A period that is not a numberperiod must be a number: <value>
A period other than 10 or 60unsupported period: 30
  • Only an absent or undefined option falls back to the binding’s simple value.
  • A call without key counts under the empty string.
  • Cloudflare’s public types list only key. A TypeScript Worker that passes limit or period needs 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 limit through.
  • The actor’s class is the internal openorange:ratelimit. RivetKit shows it as Rate Limiting (Orange). The binding table of orange dev shows each binding as a Rate Limiter on a Rivet Actor.
  • The window is floor(now / period). Each row of the openorange_ratelimit_buckets table 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 as Retry-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.ts runs a real orange dev with 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.ts covers both configuration forms and their errors.
  • The runnable example tests/fixtures/examples/rate-limiting layers a per-IP limit, a per-user limit with a higher limit for pro users, and login throttling with 429 and Retry-After. tests/examples/runnable-examples.test.ts runs 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
  • Pass: example: rate-limiting