A useful API rate limit needs more than a number. Define what is counted, whose allowance is consumed, the period it covers, and what happens when it is exhausted.
For bot protection, those decisions should reflect the operation's cost and the legitimate client's job. One global requests-per-second rule can be too strict for a harmless batch client and too generous for an expensive endpoint.
HTTP 429 communicates excessive requests and may include a Retry-After header. The standard does not choose the identity key, counting method, or business allowance for you.
Start with the resource you want to protect
List the operation and the constrained resource: request-handling capacity, database work, a third-party call, or access to a valuable dataset. If one request can create many units of work, count those units as well as incoming requests.
A read of one cached object and a request for a large generated report should not automatically consume identical allowances. You may still need a coarse request cap, but it should not be your only bound.
Also distinguish rate from concurrency. A slow operation can occupy workers long after it was admitted. Limiting starts per minute does not directly limit the number of operations still running.
Choose independent counting scopes
OWASP's bot-management guidance describes account, source, and endpoint limits. Each answers a different question.
Consider a hypothetical login service. A counter keyed only by the combination of source IP and username creates a fresh allowance for each pair. It does not independently bound all attempts against one account or all accounts attempted by one source.
The broader design lesson is to write each intended constraint separately before choosing storage keys.
| Budget | Intended bound | Legitimate case to review |
|---|---|---|
| Per credential | Work attributable to one client | Scheduled partner batch |
| Per account or tenant | Aggregate account consumption | Several users working together |
| Per route | Demand on one service function | A product launch affecting that route |
| Per source | Coarse anonymous request pressure | Shared office or mobile network |
| Concurrent operations | Work still occupying capacity | Slow but permitted jobs |
Not every endpoint needs every budget. Add the scopes that correspond to an actual risk or capacity constraint.
Allow the burst the workflow needs
A client may legitimately load several resources together or reconnect after a brief interruption. Choose burst and sustained allowances using representative traffic, not an example copied from another service.
Record the period used for observation and the client classes included. Check whether average rates hide short spikes or whether the observed sample excluded your busiest approved integration.
For expensive work, consider queue admission or a job interface instead of asking clients to retry the synchronous operation repeatedly. Keep the queue bounded too.
Make rejection and retries agree
Return the documented status and response shape. If a retry delay is exposed, make it useful for cooperative clients without disclosing unnecessary account or detector details.
Review retry behavior in official clients and partner SDKs. Immediate automatic retries can turn a controlled refusal into additional load. An unknown outcome for a state-changing operation needs retry-safe business semantics, not simply a longer delay.
Do not cache a personalized limit decision as though it were a public page. Check the actual CDN and application behavior around error responses.
Roll out a policy you can explain
Before enforcement, record which requests a candidate budget would reject. Review a busy legitimate workflow and a suspected abuse sequence. Write down the reason for each selected threshold and how to roll it back.
After enforcement, inspect completed work, rejected requests, and customer impact together. A lower request rate is useful only if the protected operation remains available to the intended clients.
Continue with API abuse investigation to distinguish policy violations from approved automation. The API abuse use case provides the product context; the budget worksheet gives that evaluation a concrete requirement.