<!-- Generated from models/_canonical by scripts/build-model-variants.js. Edit the canonical source, not this file. Behavioural profile for ChatGPT: scripts/model-profiles.json -->

#Scope contract

FILE_ISOLATION: Modify only files inside the scope the task names. Reading elsewhere is allowed; writing outside it is not, and a needed out-of-scope change is reported, not made. SIGNATURE_PINNING: Before implementing, write the exact signatures you will add or change (name, parameters, return type). Implement to those signatures; if one must change, say so before changing it. TYPE_CONTRACTS: Every public function carries explicit parameter and return types. No any, untyped dict, or interface{} at a module boundary.

---

#Purpose

Rules for limiting request rates. Two distinct goals, often conflated:

• Protection — keep one caller from exhausting capacity for everyone.
• Fairness / monetisation — enforce plan quotas.

They need different keys, different windows, and different responses. Decide which one each limiter serves before configuring it.

---

#Algorithms

Token bucket is the default. It expresses the real requirement — a sustained rate plus an allowance for bursts — in two numbers, and it costs two values per key.

lua
-- Atomic token bucket in Redis. Read-then-write in application code races.
local bucket = redis.call("HMGET", KEYS[1], "tokens", "ts")
local tokens = tonumber(bucket[1]) or tonumber(ARGV[3])
local ts     = tonumber(bucket[2]) or tonumber(ARGV[4])
local delta  = math.max(0, tonumber(ARGV[4]) - ts)
tokens = math.min(tonumber(ARGV[3]), tokens + delta * tonumber(ARGV[1]))
if tokens < 1 then return {0, tokens} end
redis.call("HMSET", KEYS[1], "tokens", tokens - 1, "ts", ARGV[4])
redis.call("EXPIRE", KEYS[1], tonumber(ARGV[2]))
return {1, tokens - 1}

Fixed windows are tempting because they are trivial, but a client can send the full limit at 59.9s and again at 60.1s — twice the intended rate. Do not use them for anything protective. → Database/redis

---

#Choose the key deliberately

Limit on more than one key at once. Per-IP alone does not stop a distributed credential-stuffing run against one account; per-account alone lets one host spray many accounts. → Security/authentication

Determine the client IP correctly. Behind a proxy, X-Forwarded-For is client-controlled unless you take the value at a known hop count from a trusted proxy set. Trusting the leftmost value lets any caller forge an unlimited number of identities and bypass the limiter entirely.

Weight expensive routes rather than counting all requests as one. A report endpoint costing 30 database seconds should consume more tokens than a health check.

---

#Respond correctly

yaml
HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 30

• 429, never 403 — clients and SDKs retry on 429 and give up on 403.
• Retry-After is mandatory. Without it, well-behaved clients retry immediately and make the overload worse.
• Send RateLimit-* headers on successful responses too, so clients can slow down before they are blocked.
• Use 503 with Retry-After for whole-service overload, distinct from a per-caller 429.

Publish the limits in your documentation. An undocumented limit is discovered during an integration's launch.

---

#Distributed enforcement

Per-instance counters mean the effective limit is limit × instances, and it changes when you autoscale.

• Use a shared store (Redis) with an atomic check-and-decrement — the Lua script above, not GET then SET.
• Decide the failure mode explicitly: if the limiter's store is unavailable, do you fail open (serve traffic, unprotected) or fail closed (reject everything)? Fail open is usually right for an API, fail closed for a login endpoint. Write the decision down.
• Prefer enforcement at the edge (CDN/WAF/API gateway) for volumetric abuse — a request rejected at the edge costs you nothing.
• Local in-process limiting is a reasonable second layer, never the only one.

nginx
# Edge layer: reject volumetric abuse before it reaches an application process
limit_req_zone $binary_remote_addr zone=api:20m rate=20r/s;
limit_req      zone=api burst=40 nodelay;
limit_req_status 429;

ts
// Application layer: quota per API key, atomic, shared across instances
const { allowed, remaining } = await bucket.take(`rl:key:${apiKey}:${route}`, {
  refillPerSecond: 10,
  capacity: 100,
  cost: ROUTE_COST[route] ?? 1,
});
if (!allowed) return res.status(429)
  .set({ "Retry-After": "30", "RateLimit-Remaining": "0" }).end();

---

#Do not punish legitimate clients

• Warn before enforcing. Ship a new limit in log-only mode, measure who would have been blocked, then enforce.
• Give a higher burst allowance than the sustained rate; real clients are bursty.
• Exempt health checks, and internal service-to-service traffic that has its own backpressure.
• Never permanently lock an account on rate-limit breach — that is a denial-of-service primitive against your own users. Use temporary backoff.
• Provide a documented path to a raised limit.

---

#Anti-patterns

---

#Checklist

• Each limiter's purpose — protection or quota — is stated
• The algorithm is token bucket or sliding window, not a fixed window
• Counter updates are atomic
• Limits are enforced from a shared store, not per instance
• Limiting keys on both identity and network address
• Client IP is derived from a trusted-proxy hop count
• Expensive routes consume proportionally more budget
• 429 is returned with Retry-After
• RateLimit-* headers are sent on successful responses
• Service-wide overload returns 503, distinct from per-caller 429
• Store-unavailable behaviour is an explicit, documented decision
• Volumetric abuse is rejected at the edge
• New limits ship in log-only mode first
• Limits are documented, with a path to request an increase