API Rate Limiter

---
name: api-rate-limiter
description: |
  Trigger when the user asks to add rate limiting, throttle requests, prevent
  abuse, or protect an endpoint from being hammered. Phrases: "rate limit",
  "throttle", "abuse prevention", "DDoS protection", "requests per minute".
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
---

# API Rate Limiter

Add rate limiting to an HTTP API with the right algorithm for the endpoint.
Covers token bucket, sliding window, and per-user vs per-IP tradeoffs.

## Prerequisites

- Redis or in-memory store available
- Framework identified (Express, Fastify, Next.js route handlers, Hono)

## Steps

1. **Decide the dimension.** Rate limit by:
   - **IP** for unauthenticated public endpoints (signup, password reset)
   - **User ID** for authenticated endpoints (API keys, session users)
   - **API key** for paid API endpoints (tier-based limits)
   - **Both IP and user** for high-value protected endpoints

2. **Pick the algorithm:**
   - **Fixed window** - simplest, bursty at boundaries. OK for minute-level limits.
   - **Sliding window** - smooths boundaries, slightly more expensive. Default choice.
   - **Token bucket** - allows bursts up to a cap. Best for human-facing APIs.
   - **Leaky bucket** - enforces strict rate regardless of burst. Best for upstream-protecting.

3. **Implement with Redis** for multi-instance correctness. Upstash example:
   ```ts
   import { Ratelimit } from "@upstash/ratelimit";
   const ratelimit = new Ratelimit({
     redis,
     limiter: Ratelimit.slidingWindow(10, "60 s"),
     analytics: true,
   });
   const { success, limit, remaining, reset } = await ratelimit.limit(userId);
   ```

4. **Return proper headers.** Every rate-limit response should include:
   - `X-RateLimit-Limit` - the limit
   - `X-RateLimit-Remaining` - how many left
   - `X-RateLimit-Reset` - when it resets (unix timestamp)
   - `Retry-After` - seconds to wait (on 429)

5. **Return 429** when over limit, not 503 or 400.

## Patterns that trip people up

- In-memory rate limits break in multi-instance deployments. Use Redis.
- Rate-limit the signup endpoint harder than the login endpoint. Password
  reset harder still.
- Don't rate-limit by IP for authenticated endpoints. Users behind a NAT
  will conflict.
- Free tier vs paid tier needs two rate limiters, not one with a coefficient.

## Output

- Middleware or handler wrapper applied to target routes
- Redis config documented
- Rate-limit headers present in responses
- Integration test for 429 path