Rate Limiting and Throttling Design Template

Per API key is the most common and flexible approach for authenticated APIs. It maps directly to billing tiers and is easy to override for individual accounts. Add per-IP limits as a secondary layer for unauthenticated endpoints (login, signup, public data) to prevent abuse. Per-user limits add complexity and are only needed when multiple API keys share a single user's quota.

Start with your current traffic data. Look at P95 request rates for your busiest legitimate consumers. Set limits at 2-3x that level so normal usage never hits the limit. Free tier limits should be generous enough for evaluation but low enough that production workloads need a paid plan. Monitor 429 rates after launch and adjust. Limits that are too aggressive create support tickets. Limits that are too generous provide no protection.

Rate limiting rejects requests that exceed the limit with a 429 response. The consumer gets an immediate error and must retry later. Throttling slows down requests by queuing them and processing at a fixed rate. Rate limiting is standard for APIs because consumers can implement their own backoff logic. Throttling is used for internal systems where queue-based processing is acceptable. Use the [API gateway](/glossary/api-gateway) glossary entry for more context on where these controls are enforced.

Consumers should implement exponential backoff with jitter. Read the `Retry-After` header and wait at least that many seconds before retrying. Add random jitter (0-1 second) to prevent thundering herd problems when many consumers hit the limit simultaneously. Document this pattern with code samples in your developer portal. The [Developer Portal Template](/templates/developer-portal-template) covers what documentation to include.

Yes. Provide a self-serve upgrade path (higher paid tier = higher limits) and a manual request process for enterprise accounts that need custom limits. Custom limits should be configurable per API key without code changes. Track which accounts request increases. If many accounts on the same tier are hitting limits, the tier's limits may be too low for your target use case. ---