Skip to content
build-3000
security

Rate Limiting and Abuse Control

Quotas on every door - because someone, somewhere, will loop your endpoint all night.

Before this: Caching Layers

Objective

Protect every endpoint with layered quotas: centralize throttling middleware, survive restarts and multiple instances, answer abusers with honest 429s, and rehearse an attack against your own API.

Vocabulary

The words to use when directing your agent.

throttle
Enforcing a maximum rate of requests from one caller.
quota
A budget of actions per window - per minute, hour or day.
429 Too Many Requests
The status code telling a client it exceeded its quota.
Retry-After
A response header saying when the caller may try again.
token bucket
A throttling model where requests spend tokens that refill steadily.

Understand it

Layered limits beat one big wall

Professional APIs stack limits: a generous global default per account, stricter caps on expensive endpoints (exports, searches), brutal caps on sensitive ones (password change, login retries - which Level 2 already gave you). Layering means abuse degrades gracefully instead of tripping one cliff for everyone.

Identity and spoofed headers

Whom do you limit? Logged-in users by account id; anonymous traffic by IP. But IPs arrive via proxy chains - blindly trusting a client-supplied forwarding header lets attackers rotate fake identities freely. Know which header your hosting platform actually sets, and trust only that one. This single detail separates decorative limits from real ones.

Core concepts

Costs are asymmetric

A scripted loop costs its author pennies and can cost you real money, degraded service for everyone, or burned third-party quotas. Rate limits convert unlimited exposure into bounded exposure. They protect availability first, budgets second, feelings never.

Counters must outlive processes

In-memory counters reset on every deploy and disagree between instances. Real limits need shared state - the same shared-store lesson caching taught, applied to security. If restarting your server resets the attacker's budget, you have built an attack rehearsal mode.

Examples

The honest 429

Over-limit callers receive 429 with a Retry-After header and the standard error envelope - not silence, not a hang, not a 500. Well-behaved clients back off automatically; badly-behaved ones are now easy to spot in logs by volume.

Reading abuse in logs

One account id appearing thousands of times per minute in access logs is not a power user - it is a script. Limits plus logs turn noise into named, blockable actors.

Common mistakes

Common mistake

Throttling only the routes the UI calls, leaving raw API paths wide open.

Fix

Limits attach at the router level covering EVERY route, with per-route overrides - not sprinkled on popular handlers.

Common mistake

Keying anonymous limits off a spoofable forwarded-for header.

Fix

Use the connection IP your platform provides; document which header is trusted and why.

Working with your AI agent

Demand the limit table before implementation: route x scope (per-account/per-IP) x cap x window x response behavior. One middleware owns enforcement; routes declare which row applies. Any limit logic living inside individual handlers should be treated as a review-blocking smell.

Build it

The module’s real project. Your agent builds; you direct and inspect.

Project: Throttle Wall

Wrap the Private Ledger in layered rate limits: a default per-account quota everywhere, strict caps on sensitive operations, durable shared counters, honest 429 envelopes - then run an abuse drill against yourself and document what broke.

Requirements

  • Default quota applies to every route via one middleware; overrides declared per route class
  • Sensitive operations (password change, export creation) carry tighter caps than reads
  • Counters live in shared/durable storage - limits survive a server restart
  • Over-limit responses: 429 status, standard error envelope, Retry-After header set
  • Abuse drill documented: a script hammers three endpoints; observed behavior and log evidence recorded

Context for your agent

Implement layered rate limiting for my Expense Ledger as one centralized middleware. Limit table first: default per-account quota on all routes, tighter classes for password-change and exports, generous for reads. Counters in the same shared-store pattern as my cache so they persist across restarts and instances. Over-limit returns 429 envelope with Retry-After. Anonymous traffic keys off the platform-provided connection IP - show me where that comes from in my hosting setup. Then write the abuse-drill script.

Verify it - twice

Check every item yourself first. Then hand your agent the prompt and compare verdicts.

Self-verified0/9
Functional
Architecture
Security
Testing
Production

Verification prompt - paste into your AI agent

Attack my Throttle Wall as an abusive scripter with a grudge and a budget. Attempt, reporting observed behavior for each: (1) hammer a read endpoint past its cap - do 429s arrive with Retry-After?, (2) hammer password-change - is its tighter class actually tighter?, (3) evade as an anonymous caller by spoofing forwarding headers - did identity rotation work?, (4) restart-timing exploit - if the server restarted mid-attack, would my budget reset? Verify each against my DoD as PASS or FAIL, then name the cheapest change that would hurt your attack the most.

Run this against “Rate Limiting and Abuse Control” after your own checklist pass. Where the agent and you disagree, investigate before moving on.

Review questions

Answer out loud. If you cannot, revisit before moving on.

  1. Recite your limit table: which route classes exist and why those boundaries?

  2. Why do in-memory counters fail two different ways under real deployment?

  3. What makes a 429 response 'honest' compared to other ways of shedding load?

You can now

  • Design layered quotas that bound worst-case abuse
  • Centralize throttling so no route ships unprotected
  • Rehearse attacks against your own API before strangers do

Up next

Database Indexing and Performance