Rate limiting

Limits per API key, user or IP address, with exact arithmetic, standard headers and a table of cases every build must pass.

This is an app part spec on Spekkr, published by vex. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.

Spec
vex/rate-limiting
Version
0.1.2
Published by
vex
Updated
15 Nov 2026

Build this spec

Build the spec at https://spekkr.com/vex/rate-limiting/start.md.

Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.

Published by vex.

What does the result look like?

Rate limiting: rate limit deskRate limiting: rate limit signinRate limiting: rate limit casesRate limiting: rate limit mobile

What can I customize?

Where counts are kept Memory only suits an app that runs as one process.

Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.

What do I get?

  • spec.md Requirements and acceptance criteria.

    Rate limiting

    What this builds

    A limiter that sits in front of an app's routes. Each caller may make so many requests in a window. A caller over the limit gets status 429 and is told when to come back. The arithmetic is exact, so every build of this spec refuses the same requests.

    Read spekkr.inputs.json first. default_limit requests are allowed every default_window_seconds seconds. store says where counts are kept. per_route_limits decides whether R4 exists and response_headers whether the headers in R3 are sent.

    Out of scope

    • Protection against a flood meant to take the app down. That belongs in front of the app, at the network edge.
    • Quotas per month and billing by usage.
    • Queueing requests instead of refusing them.

    Requirements

    Each requirement has an id. Tests name the id they cover.

    R1. The limit
    • A limit is a number of requests and a window. A caller who has been idle can make that many requests at once, and after that one more every window divided by limit.
    • The limiter keeps one number per caller and limit, and follows the algorithm in design.md in whole milliseconds. It does not use floating point.
    • A refused request does not count against the caller.

    Accept when: the table of cases in design.md passes exactly, row by row.

    R2. Who the caller is
    • The caller is the first of these that the request has: an API key's id, a signed-in user's id, the IP address.
    • The IP address is the address of the connection. A forwarding header is believed only when the connection comes from an address listed in TRUSTED_PROXIES, and then the right-most address that is not itself a trusted proxy is used.
    • An IPv6 address is counted by its first 64 bits.

    Accept when: a forged forwarding header from an untrusted address is ignored, and two addresses in the same IPv6 /64 share one count.

    R3. The answer
    • A refused request gets status 429, a JSON body with a code and a message, and a Retry-After header: the wait in whole seconds, rounded up.
    • If response_headers is on, every answer, allowed or refused, carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Reset is the number of seconds, rounded up, until the caller has the whole limit again.
    • The limiter runs before the route's own work. The default limit is checked before the request body is read.

    Accept when: a caller who waits exactly Retry-After seconds is allowed, and the headers match the table in design.md.

    R4. Limits for single routes

    Only if per_route_limits is on.

    • A route can name a limit of its own, with a name, a number and a window. For example sign_in: 5 requests in 900 seconds.
    • A named limit is counted apart from the default. A request to such a route must pass both.
    • A named limit can say what to count by, such as the email address in a sign-in form in place of the caller. Only such a limit reads the body. It does so after the default limit has passed, and hands the body on to the route unchanged. A request without that field is counted by the caller.

    Accept when: using up sign_in leaves the default untouched, and a request that passes one limit and fails the other is refused without counting against the one it passed.

    R5. Two requests at once
    • Checking and counting are one step. Two requests that arrive together can never both take the last place.

    Accept when: 50 requests sent at the same moment against a limit of 10 produce exactly 10 allowed and 40 refused, in every store.

    R6. When the store is down
    • If the store cannot be reached inside 100 milliseconds, the request is allowed and the failure is logged, at most once a minute.
    • A named limit can be marked strict. A strict limit refuses with status 503 when the store is down.

    Accept when: with the store stopped, an ordinary route answers and a strict one gets 503.

    R7. Exemptions
    • A health-check route is never limited.
    • Callers listed in RATE_LIMIT_EXEMPT, by API key id or IP address, are never limited.

    Accept when: an exempt caller makes 1,000 requests in a second and none is refused.

    R8. Keeping the store small
    • A caller's number is forgotten once the caller would have the whole limit again.
    • With store set to memory, at most 100,000 callers are remembered, and the ones idle longest are dropped first.

    Accept when: after a window with no requests the store holds nothing for the caller.

    Definition of done

    • Every acceptance check above has an automated test, and all tests pass. Tests set the clock; none of them sleeps.
    • A README explains how to put the limiter in front of a route, how to name a limit, and how to run the tests.
    # Rate limiting
    
    ## What this builds
    
    A limiter that sits in front of an app's routes. Each caller may make so many
    requests in a window. A caller over the limit gets status 429 and is told when to
    come back. The arithmetic is exact, so every build of this spec refuses the same
    requests.
    
    Read `spekkr.inputs.json` first. `default_limit` requests are allowed every
    `default_window_seconds` seconds. `store` says where counts are kept.
    `per_route_limits` decides whether R4 exists and `response_headers` whether the
    headers in R3 are sent.
    
    ## Out of scope
    
    - Protection against a flood meant to take the app down. That belongs in front of
      the app, at the network edge.
    - Quotas per month and billing by usage.
    - Queueing requests instead of refusing them.
    
    ## Requirements
    
    Each requirement has an id. Tests name the id they cover.
    
    ### R1. The limit
    
    - A limit is a number of requests and a window. A caller who has been idle can make
      that many requests at once, and after that one more every window divided by
      limit.
    - The limiter keeps one number per caller and limit, and follows the algorithm in
      `design.md` in whole milliseconds. It does not use floating point.
    - A refused request does not count against the caller.
    
    Accept when: the table of cases in `design.md` passes exactly, row by row.
    
    ### R2. Who the caller is
    
    - The caller is the first of these that the request has: an API key's id, a
      signed-in user's id, the IP address.
    - The IP address is the address of the connection. A forwarding header is believed
      only when the connection comes from an address listed in `TRUSTED_PROXIES`, and
      then the right-most address that is not itself a trusted proxy is used.
    - An IPv6 address is counted by its first 64 bits.
    
    Accept when: a forged forwarding header from an untrusted address is ignored, and
    two addresses in the same IPv6 /64 share one count.
    
    ### R3. The answer
    
    - A refused request gets status 429, a JSON body with a code and a message, and a
      `Retry-After` header: the wait in whole seconds, rounded up.
    - If `response_headers` is on, every answer, allowed or refused, carries
      `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. Reset is the
      number of seconds, rounded up, until the caller has the whole limit again.
    - The limiter runs before the route's own work. The default limit is checked
      before the request body is read.
    
    Accept when: a caller who waits exactly `Retry-After` seconds is allowed, and the
    headers match the table in `design.md`.
    
    ### R4. Limits for single routes
    
    Only if `per_route_limits` is on.
    
    - A route can name a limit of its own, with a name, a number and a window. For
      example `sign_in`: 5 requests in 900 seconds.
    - A named limit is counted apart from the default. A request to such a route must
      pass both.
    - A named limit can say what to count by, such as the email address in a sign-in
      form in place of the caller. Only such a limit reads the body. It does so after
      the default limit has passed, and hands the body on to the route unchanged. A
      request without that field is counted by the caller.
    
    Accept when: using up `sign_in` leaves the default untouched, and a request that
    passes one limit and fails the other is refused without counting against the one it
    passed.
    
    ### R5. Two requests at once
    
    - Checking and counting are one step. Two requests that arrive together can never
      both take the last place.
    
    Accept when: 50 requests sent at the same moment against a limit of 10 produce
    exactly 10 allowed and 40 refused, in every `store`.
    
    ### R6. When the store is down
    
    - If the store cannot be reached inside 100 milliseconds, the request is allowed
      and the failure is logged, at most once a minute.
    - A named limit can be marked `strict`. A strict limit refuses with status 503
      when the store is down.
    
    Accept when: with the store stopped, an ordinary route answers and a strict one
    gets 503.
    
    ### R7. Exemptions
    
    - A health-check route is never limited.
    - Callers listed in `RATE_LIMIT_EXEMPT`, by API key id or IP address, are never
      limited.
    
    Accept when: an exempt caller makes 1,000 requests in a second and none is refused.
    
    ### R8. Keeping the store small
    
    - A caller's number is forgotten once the caller would have the whole limit again.
    - With `store` set to `memory`, at most 100,000 callers are remembered, and the
      ones idle longest are dropped first.
    
    Accept when: after a window with no requests the store holds nothing for the
    caller.
    
    ## Definition of done
    
    - Every acceptance check above has an automated test, and all tests pass. Tests set
      the clock; none of them sleeps.
    - A README explains how to put the limiter in front of a route, how to name a
      limit, and how to run the tests.
    

    Open spec.md as plain text

  • design.md Data model, rules and flows.

    Design

    This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them.

    The algorithm

    All times are whole milliseconds. For a limit of limit requests per window:

    interval = window / limit          (whole milliseconds, rounded down)
    stored   = the caller's number, or now if there is none
    start    = max(stored, now)
    ahead    = start - now
    
    if ahead > window - interval:
        refuse; retry_after = ahead - (window - interval)
    else:
        store start + interval, to expire at start + interval
        allow; remaining = (window - (start + interval - now)) / interval, rounded down

    reset is start + interval - now when allowed and ahead when refused. Retry-After and RateLimit-Reset are those values in seconds, rounded up.

    A limit with more requests than its window has milliseconds would have an interval of zero. That is a configuration error. Refuse to start with it.

    Cases

    A limit of 3 requests per 60 seconds, one caller, nothing stored at the start.

    Request at, msResultRemainingRetry after, msStored afterwards
    0allowed220000
    1000allowed140000
    2000allowed060000
    3000refused01700060000
    20000allowed080000
    20500refused01950080000
    100000allowed2120000

    The refused request at 3000 gets Retry-After: 17. The one at 20500 gets Retry-After: 20.

    The store

    The stored key is the limit's name, a colon and the caller, for example default:key_3kTn9QxWb2aZ. The default limit is the default_limit input per default_window_seconds.

    storeHow the one step is made
    redisOne script that reads, decides and writes, with the key's expiry set to the stored time. Pass now in from the app, so tests can set it.
    databaseOne table, rate_limits(key, stored, expires_at). One transaction that locks the row, or one statement that inserts or updates and returns the result. Sweep expired rows once a minute.
    memoryA map behind one lock, with the least recently used entry dropped at 100,000.

    Hide the three behind one interface with one operation: take(limits, now), where limits is a list of key, limit and window. It decides for every entry and writes only if all of them allow. It returns, for each entry, allowed or refused with remaining, retry_after and reset.

    Order of work for a request

    1. If the route is the health check, or the caller is exempt, pass.
    2. Work out the caller.
    3. Take from every limit that applies, in one call. If any refuses, nothing is counted. Answer 429 with the longest retry_after.
    4. Set the headers from the limit with the least remaining.

    Configuration

    SettingPurpose
    REDIS_URLConnection string, when store is redis.
    DATABASE_URLConnection string, when store is database.
    TRUSTED_PROXIESAddresses or ranges whose forwarding header is believed. Empty by default.
    RATE_LIMIT_EXEMPTAPI key ids and IP addresses that are never limited. Empty by default.

    Named here

    • The app says who is calling through one function, caller(request), which answers with an API key's id, a user's id, or neither. The example app reads the key from Authorization: Bearer <key>.
    • The forwarding header is X-Forwarded-For. If every address in it is a trusted proxy, the left-most is used.
    • An IPv4 address written inside IPv6 is counted as the IPv4 address.
    • A refused request's body is {"error": {"code": "rate_limited", "message": "..."}}. A strict limit with the store down answers 503 with the code store_unavailable.
    • The three headers hold whole numbers, such as RateLimit-Reset: 17. When two limits apply they describe the one with less remaining, and the default limit on a tie.

    What this spec leaves to you

    Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.

    # Design
    
    This file fixes the parts that are easy to get wrong. Choose the language and
    framework that fit the person's project; nothing here depends on them.
    
    ## The algorithm
    
    All times are whole milliseconds. For a limit of `limit` requests per `window`:
    
    ```
    interval = window / limit          (whole milliseconds, rounded down)
    stored   = the caller's number, or now if there is none
    start    = max(stored, now)
    ahead    = start - now
    
    if ahead > window - interval:
        refuse; retry_after = ahead - (window - interval)
    else:
        store start + interval, to expire at start + interval
        allow; remaining = (window - (start + interval - now)) / interval, rounded down
    ```
    
    `reset` is `start + interval - now` when allowed and `ahead` when refused.
    `Retry-After` and `RateLimit-Reset` are those values in seconds, rounded up.
    
    A limit with more requests than its window has milliseconds would have an interval
    of zero. That is a configuration error. Refuse to start with it.
    
    ## Cases
    
    A limit of 3 requests per 60 seconds, one caller, nothing stored at the start.
    
    | Request at, ms | Result | Remaining | Retry after, ms | Stored afterwards |
    | --- | --- | --- | --- | --- |
    | 0 | allowed | 2 | | 20000 |
    | 1000 | allowed | 1 | | 40000 |
    | 2000 | allowed | 0 | | 60000 |
    | 3000 | refused | 0 | 17000 | 60000 |
    | 20000 | allowed | 0 | | 80000 |
    | 20500 | refused | 0 | 19500 | 80000 |
    | 100000 | allowed | 2 | | 120000 |
    
    The refused request at 3000 gets `Retry-After: 17`. The one at 20500 gets
    `Retry-After: 20`.
    
    ## The store
    
    The stored key is the limit's name, a colon and the caller, for example
    `default:key_3kTn9QxWb2aZ`. The default limit is the `default_limit` input per
    `default_window_seconds`.
    
    | `store` | How the one step is made |
    | --- | --- |
    | `redis` | One script that reads, decides and writes, with the key's expiry set to the stored time. Pass `now` in from the app, so tests can set it. |
    | `database` | One table, `rate_limits(key, stored, expires_at)`. One transaction that locks the row, or one statement that inserts or updates and returns the result. Sweep expired rows once a minute. |
    | `memory` | A map behind one lock, with the least recently used entry dropped at 100,000. |
    
    Hide the three behind one interface with one operation: `take(limits, now)`, where
    `limits` is a list of key, limit and window. It decides for every entry and writes
    only if all of them allow. It returns, for each entry, allowed or refused with
    `remaining`, `retry_after` and `reset`.
    
    ## Order of work for a request
    
    1. If the route is the health check, or the caller is exempt, pass.
    2. Work out the caller.
    3. Take from every limit that applies, in one call. If any refuses, nothing is
       counted. Answer 429 with the longest `retry_after`.
    4. Set the headers from the limit with the least remaining.
    
    ## Configuration
    
    | Setting | Purpose |
    | --- | --- |
    | `REDIS_URL` | Connection string, when `store` is `redis`. |
    | `DATABASE_URL` | Connection string, when `store` is `database`. |
    | `TRUSTED_PROXIES` | Addresses or ranges whose forwarding header is believed. Empty by default. |
    | `RATE_LIMIT_EXEMPT` | API key ids and IP addresses that are never limited. Empty by default. |
    
    ## Named here
    
    - The app says who is calling through one function, `caller(request)`, which
      answers with an API key's id, a user's id, or neither. The example app reads
      the key from `Authorization: Bearer <key>`.
    - The forwarding header is `X-Forwarded-For`. If every address in it is a
      trusted proxy, the left-most is used.
    - An IPv4 address written inside IPv6 is counted as the IPv4 address.
    - A refused request's body is `{"error": {"code": "rate_limited", "message":
      "..."}}`. A strict limit with the store down answers 503 with the code
      `store_unavailable`.
    - The three headers hold whole numbers, such as `RateLimit-Reset: 17`. When two
      limits apply they describe the one with less remaining, and the default limit
      on a tie.
    
    ## What this spec leaves to you
    
    Where this spec names something, use that name, so that two builds of it agree.
    Where it does not, the choice is yours. List what you chose in the README.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    Tasks

    Work in order. Finish a task's check before starting the next.

    1. Set up. A test runner, a clock that tests can set, and the smallest app to put the limiter in front of if there is none: one route and a health check. Check: an empty test run passes.
    2. The algorithm (R1). A pure function from the stored number, now, the limit and the window to a result, with no store at all. Check: a test walks the table of cases in design.md and every row matches.
    3. The store (R5, R8). The interface in design.md for the store input. Check: the R5 test with 50 requests at once passes, and the R8 test passes.
    4. The caller (R2). Check: the R2 acceptance tests pass.
    5. The answer (R3). Status 429, Retry-After, and the three headers if response_headers is on. Use default_limit and default_window_seconds. Check: the R3 acceptance tests pass.
    6. Named limits (R4). Only if per_route_limits is on. Check: the R4 acceptance tests pass.
    7. Store failures (R6) and exemptions (R7). Check: the R6 and R7 acceptance tests pass.
    8. Finish. Write the README and run the whole test suite. Check: every item under "Definition of done" in spec.md is true.
    # Tasks
    
    Work in order. Finish a task's check before starting the next.
    
    1. **Set up.** A test runner, a clock that tests can set, and the smallest app to
       put the limiter in front of if there is none: one route and a health check.
       Check: an empty test run passes.
    
    2. **The algorithm (R1).** A pure function from the stored number, `now`, the limit
       and the window to a result, with no store at all.
       Check: a test walks the table of cases in `design.md` and every row matches.
    
    3. **The store (R5, R8).** The interface in `design.md` for the `store` input.
       Check: the R5 test with 50 requests at once passes, and the R8 test passes.
    
    4. **The caller (R2).**
       Check: the R2 acceptance tests pass.
    
    5. **The answer (R3).** Status 429, `Retry-After`, and the three headers if
       `response_headers` is on. Use `default_limit` and `default_window_seconds`.
       Check: the R3 acceptance tests pass.
    
    6. **Named limits (R4).** Only if `per_route_limits` is on.
       Check: the R4 acceptance tests pass.
    
    7. **Store failures (R6) and exemptions (R7).**
       Check: the R6 and R7 acceptance tests pass.
    
    8. **Finish.** Write the README and run the whole test suite.
       Check: every item under "Definition of done" in `spec.md` is true.
    

    Open tasks.md as plain text

Is it for me?

Platforms
backend

What does it need?

Accounts
A Redis server, if counts are kept in Redis
Agent permissions
shell, network
Secrets it reads
REDIS_URL DATABASE_URL

What changed?

  • 0.1.215 Nov 2026Names what it builds.
  • 0.1.114 Nov 2026Says "person" where it said "buyer".
  • 0.1.014 Nov 2026Moved from dwrtz/rate-limiting.

For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.