API Rate Limiter Designer

Rate limiting design: token bucket in Redis, keyed by API key, tiered per plan, with a separate stricter limit on the batch endpoint.

Algorithm

• Token bucket via an atomic Redis Lua script: allows short bursts, enforces a steady rate.
• nginx limit_req per IP as a coarse outer guard against unauthenticated floods.

Limit keys

Tier structure

Values are starting points to tune against your capacity.

429 and headers

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 5
RateLimit-Remaining: 0
RateLimit-Reset: 3
Retry-After: 3
{"error":"rate_limited","limit_scope":"batch"}

Send the RateLimit-* headers on every response, not only on 429.

Monitoring

• Count 429s by plan, key and endpoint group.
• Alert when one key produces most of the 429s or Redis script latency rises.
• Fail open with a local in-memory limit if Redis is unreachable.

Next steps

• Publish the limits in your API docs before enforcing them.
• Roll out in log-only mode for a week, then enforce.