A Practical Guide to API Rate Limiting

By Owen Gallagher · June 26, 2026 · Engineering

Rate limiting is one of those features everyone agrees is important and almost nobody designs deliberately. The naive per-IP token bucket works until you meet carrier-grade NAT, where a hundred thousand mobile users share a handful of addresses and your limiter punishes them as a single entity.

A better default is layered limiting: a coarse per-IP bucket at the edge, an authenticated per-token bucket in the application, and a global circuit breaker that sheds load before your database does it for you. Each layer answers a different question, and each fails differently.

Whatever you choose, communicate it. A 429 with Retry-After and a clear error body turns an angry integrator into a patient one. Silence turns them into a retry storm.