Rate limiter

Requirements

Protect APIs per key and per IP; return 429 with Retry-After.

Capacity

Start at 100 QPS, 10× peak, 1 year of data. Size storage from payload bytes × QPS × retention.

API

REST plus idempotency keys on mutating endpoints.

Data model

Primary key, access pattern, retention, and the index that makes the hot query cheap.

Architecture

flowchart LR
  Client --> Gateway --> Service --> Store

Scaling

Stateless compute, shard the write path, cache the read path, queue work that can be async.

Failure modes

Dependency timeout, hot shard, cache stampede, poison message, regional outage.

Observability

RED on the edge, USE on hosts, traces across the queue, SLOs on availability and latency.

Security

Authn/z at the gateway, least privilege to data stores, no secrets in Git.

Trade-offs

Token bucket vs sliding window; local vs Redis; fairness vs cost.