API rate limiting controls how quickly a client, account, or workload can consume an endpoint. It can reduce abusive traffic, protect costly operations, and keep one noisy tenant from degrading everyone else’s experience. The useful question is not simply how many requests to allow, but which resource each request consumes and whose budget it should use.
This guide covers practical design for APIs you operate. Rate limits are one layer of a broader security and reliability strategy; they do not replace authentication, authorization, input limits, or protection against network-level denial of service.
1. Identify the resource you need to protect
Start with endpoint behavior. A static lookup, password-reset email, bulk export, file conversion, and AI inference call can have very different costs. A single global requests-per-minute limit treats them as equivalent even when one request triggers far more work.
List expensive downstream operations and their constraints. These may include database connections, external API quotas, email delivery, storage, CPU time, or billable model tokens. Define the failure you are trying to avoid: overload, excessive spend, spam, account takeover attempts, or unfair tenant access.
Measure representative normal traffic before choosing thresholds. A legitimate batch job may create short bursts that look unusual compared with interactive users. Use observed requirements and explicit product agreements rather than presenting an arbitrary number as a universally secure default.
2. Choose identities that match the threat model
IP-based limiting can be useful for unauthenticated traffic, but it has limitations. Many legitimate users can share an address behind corporate networks or mobile infrastructure. Conversely, an abusive client may operate through many addresses.
For authenticated APIs, consider account, tenant, API-key, or operation-specific budgets. Layer these with broader infrastructure limits where appropriate. Protect account-sensitive flows separately so an attacker cannot avoid a per-account control simply by changing an IP address.
Use the identity established by trusted infrastructure. If a reverse proxy supplies the client address, define which proxy headers are trusted and reject spoofed assumptions from direct clients. A rate limiter keyed by attacker-controlled header text is easy to evade.
3. Select an algorithm for the desired behavior
Fixed windows are straightforward but can allow a large burst across a window boundary. Sliding-window approaches can provide a different view of recent activity, with storage and implementation trade-offs. Token buckets commonly allow a controlled burst while replenishing capacity over time.
Choose based on your operational goal. An interactive application may benefit from brief bursts, while a costly background operation may need a stricter budget. Document whether requests consume equal units or whether expensive actions have a larger weight.
Distinguish request rate from concurrency. A limit of a certain number of requests per minute does not cap the number of long-running requests active at once. Add concurrency controls, timeouts, or queue limits when resource exhaustion depends on simultaneous work.
4. Make distributed enforcement consistent
An API running on several instances needs a deliberate coordination model. Independent in-memory counters may multiply the effective allowance as traffic moves between instances. A shared limiter can provide broader coordination but introduces its own latency and availability dependency.
Use atomic operations or an implementation designed for the selected algorithm. A read-then-write counter can lose updates under concurrency and admit more traffic than intended. Test behavior across instances instead of testing only one local process.
Decide what happens when the limiter’s storage is unavailable. Failing open may preserve availability while increasing abuse risk; failing closed may protect resources while rejecting legitimate users. The correct choice depends on the endpoint, and a documented fallback is better than accidental behavior.
5. Return actionable responses without exposing secrets
HTTP 429 Too Many Requests is the conventional response when a client exceeds an applicable rate limit. Where appropriate, provide retry guidance such as Retry-After and a clear application error code. Be consistent across gateways and application services so clients can distinguish throttling from unrelated failures.
Clients should honor retry guidance and avoid immediate repeated retries. Use bounded exponential backoff with jitter when appropriate, and consider whether the operation is safe to retry. A retry mechanism that resends a payment or job submission can create duplicate effects without idempotency controls.
Do not return other customers’ usage details or internal infrastructure information. Explain the caller’s relevant budget and recovery path. For account-sensitive workflows, avoid responses that unnecessarily disclose whether an email address or account exists.
6. Limit request size and business impact too
An attacker can send fewer requests with larger bodies or more expensive parameters. Bound payload size, pagination, nesting, processing time, and batch size as the feature requires. Apply limits before expensive parsing or downstream work whenever the architecture permits.
Sensitive actions need business-level controls. A password-reset flow may require per-account and delivery limits; an export may need job ownership and concurrency rules; an AI endpoint may need token and spending budgets. The request counter should support these decisions, not replace them.
Authorization remains essential. A rate-limited endpoint can still leak another customer’s data at a slower pace. Our API object-level authorization guide explains why authenticated identity is not permission to every record.
7. Test thresholds, recovery, and legitimate bursts
In an authorized staging environment, test just below, at, and above the configured threshold. Check window transitions, counter expiration, simultaneous requests, multiple application instances, and the effect of different client identities. Verify that rejected requests do not trigger expensive side effects before the limiter runs.
Test recovery after the budget replenishes. Confirm the retry instructions match real behavior and that clients do not remain locked out because a stale key or clock assumption prevents recovery. Exercise limiter-store failures according to your documented fallback policy.
Observe rejection rates by endpoint and authorized tenant without logging full credentials or API keys. Investigate both sharp increases and unexpectedly absent throttling. Tune thresholds through controlled changes, and keep emergency adjustments reversible.
Frequently asked questions
Is rate limiting enough to stop denial of service?
No. It can protect application resources, but volumetric attacks or infrastructure bottlenecks may need network-level controls and capacity planning. A request must reach the enforcement point before that point can reject it.
Should every endpoint have the same limit?
Usually not. Different operations consume different resources and support different user workflows. Combine a broad safety limit with narrower budgets for costly or sensitive features.
Where should a team start?
Inventory expensive actions, measure legitimate usage, select trusted identities, and document failure behavior. Review the OWASP REST Security Cheat Sheet for complementary controls, including input validation, request-size limits, and appropriate HTTP responses.
