rate limits LIVE

layer 1 — edge throttle: 100 req/min per IP

Every request passes through middleware before anything else. The rule: 100 requests per minute per client IP, sliding 60-second window.

• IP resolution (reverse-proxy aware): CF-Connecting-IP first, then the first hop of X-Forwarded-For, then X-Real-IP. Behind Cloudflare this is your real client IP, not the CDN's.
• exemptions: only GET /api/health and GET /api/status skip the throttle (public liveness probes). Everything else is counted.
• the window is a true sliding window, not a per-minute bucket: a denied request is refused when its timestamp falls within 60s of the 100th counted request.
• retry_after_seconds is the seconds until the oldest counted request ages out of the window — that's the earliest you can retry and be counted fresh.
• denied requests do not consume quota. A 429 does not add a timestamp to the window, so the window recovers exactly 60 seconds after the first counted hit — there is no penalty extension for bursting.
• in-memory per worker isolate: the counter lives in the isolate's memory, so under a multi-isolate deployment the effective limit is ~100/min per isolate for one IP. See the planned section below.
• every denial is logged with error class rate_limited, so abuse spikes show up in the /api/health error readout.

Exact 429 from layer 1 (carries a Retry-After header):

{
  "error": "rate_limited",
  "message": "Too many requests — 100 per minute per IP.",
  "retry_after_seconds": 34,
  "ip": "203.0.113.9"
}

layer 2 — per-endpoint token buckets (per key or IP)

Past the edge throttle, each endpoint family gets its own KV-backed token bucket, refilled on a fixed window. Buckets are scoped to your identity: a valid API key's scope for keyed calls, the client IP for anonymous or operator endpoints. Rejected requests do not write state — no stampede, no counter inflation.

dev-mode note: when the KV store is unbound, the bucket check is skipped entirely (limits off) — the edge throttle in layer 1 is always on regardless.

exact 429 shapes

The layers stack — layer 1 fires first. Each layer's 429 is a different shape; the body below is copied, not paraphrased.

• layer 1 — edge throttle (carries Retry-After header)
  {"error": "rate_limited", "message": "Too many requests — 100 per minute per IP.", "retry_after_seconds": 34, "ip": "203.0.113.9"}
• layer 2 — REST endpoints (/api/intel, mcp, audits, goals; carries retry-after header)
  {"ok": false, "error": "rate_limit_exceeded", "retry_after_seconds": 34}
• layer 2 — key issuance (POST /api/keys; carries retry-after header)
  {"ok": false, "error": "issuance_rate_limit_exceeded", "retry_after_seconds": 3600}
• layer 2 — v1 signal apis (POST /v1/signals/{signal}/evaluate; no Retry-After header — read the body field)
  {"request_id": "req_9f2c…", "ok": false, "error": "rate_limited", "message": "Rate limit exceeded; retry in 34s.", "retry_after_seconds": 34}

client guidance

• always honor the Retry-After header (or retry_after_seconds in the body) — it is exact for layer 1 and a best-effort refill estimate for layer 2 token buckets.
• back off exponentially with jitter if you keep hitting 429s; a fixed-interval retry loop will just ride the limit.
• remember the layers compose: a single IP making /api/intel calls faces the tiered bucket (10/min on free) inside the 100/min edge throttle. Multiple keys from one IP share the outer 100/min.
• an API key is scoped per key, not per machine: two processes sharing one key share one bucket.

what happens on abuse

Honestly, not much beyond the throttle itself — and that's deliberate:

• no IP lockout, ban list, or 403-on-abuse exists in the code. Sustained bursting gets you sustained 429s until the window recovers; there is no escalating penalty.
• denials don't consume quota and don't extend the window — the code refuses to write any state for a rejected request, so an attacker can't make the throttle stricter by poking it.
• every denial is logged (error class rate_limited with the endpoint and retry time), so an abuse spike is visible to operators in the /api/health error readout.
• known limitation: the daily quota counter is a KV read-modify-write with no transaction, so tight bursts from concurrent requests can overshoot the cap slightly. Burst metering, not hard metering — acceptable for freemium gating.

planned: cross-isolate limiter DRAFT

The layer-1 throttle is in-memory per worker isolate — the deployed code carries an explicit note that a cross-isolate limiter (Durable Object or KV-backed) is the future upgrade if bursty single-IP traffic ever becomes real. No endpoint, no config flag, and no shared-bucket behavior ships today; the real docs land on this page the day the limiter ships. Bucket names, window math, and migration behavior here are not final.