Why it matters
Rate limits should map to the resource being protected and the identity consuming it. A customer can often adapt if the limit, reset behavior and error response are clear.
Rate limits protect shared capacity and make behavior predictable for API clients. A useful limit tells developers what happened and when they can try again.
Decisions to make
- Choose per-key, per-user, per-tenant and global budgets.
- Define bursts and sustained rates separately.
- Decide whether internal jobs share the same capacity.
- Choose the unit of fairness: user, key, organization or IP address.
- Define burst allowances and which endpoints share a bucket.
Build checklist
- Return a clear limit response and retry guidance.
- Measure refusals and alert on unusual spikes.
- Test concurrent requests and distributed enforcement.
- Return clear limit headers and retry guidance.
- Test behavior when the limiter store is unavailable.
Common mistakes
- Setting one global cap that lets a noisy tenant block everyone else.
- Applying one global limit that lets one customer crowd out another.
- Using an IP address as the only identity for authenticated clients.
Tools & references
3 starting points to compare or study. Check fit, maintenance, terms and current capabilities before choosing one.
