How to add rate limiting to a SaaS API
To add rate limiting to a SaaS API, choose a key to count requests against (usually the API key, with the IP address as a fallback for anonymous routes), set a limit per endpoint group, and answer excess requests with HTTP 429 and a Retry-After header. You can enforce it at the reverse proxy, as nginx's limit_req does, or in application code with a token bucket. Start at the proxy, because it protects every route at once, and add per-customer limits in code once you have paying users.
Why bother before you have traffic
An unlimited API fails in three ways. One customer's buggy loop uses all your database connections. A scraper finds your search endpoint. Or a login route gets guessed at thousands of times a minute. A limit turns each of those into a 429 for one client instead of an outage for everyone.
The limit does not need to be clever. It needs to exist, be documented and return a response the client can act on. If you also cap AI API costs, rate limits are the front door of the same idea: control what a single caller can spend of your resources.
Step 1: choose the key
The key decides who shares a bucket.
- API key or user ID for authenticated routes. This is fair, since two customers behind one office IP do not share a limit.
- IP address for anonymous routes such as sign-up, login and password reset. Expect false sharing behind corporate networks and mobile carriers, so keep these limits loose.
- Both, for sensitive routes. Count by IP and by account, and reject when either runs out.
MDN notes that restrictions are typically based on a client's IP, and can be specific to users or authorized applications when requests are authenticated. That matches the split above.
Step 2: choose the limits
Pick numbers from what a normal client does, then add headroom. A dashboard that makes six calls on page load needs more than six per minute. A rule of thumb that works for a first version:
| Route group | Key | Starting limit |
|---|---|---|
| Login, sign-up, password reset | IP and account | 5 per minute per key |
| Search and list endpoints | API key | 20 per second |
| Normal reads and writes | API key | 50 per second |
| Webhooks you receive | Source IP | Match the sender's documented rate |
Treat these as starting points and adjust after a week of logs.
For reference, Stripe's rate limits page sets a global limit of 100 requests per second in live mode and 25 per second in a sandbox, and 25 requests per second for individual endpoints unless noted. It also applies tighter resource limits, such as 20 read requests per second on its Search API. Giving search and list routes lower limits than plain reads is a pattern you can copy.
Step 3: enforce it at the proxy
If you run nginx, the limit_req module does this with two directives. It uses the leaky bucket method, so it processes requests at the configured rate and treats extra requests as a burst up to a limit.
http {
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
server {
location /api/ {
limit_req zone=api burst=20 nodelay;
limit_req_status 429;
proxy_pass http://app;
}
}
}
What each part does, per the nginx docs:
limit_req_zonedefines a shared memory zone keyed by client address and an average rate. A 10 MB zone holds roughly 80,000 states on a 64-bit platform, since one megabyte keeps about 8,000 of the 128-byte states.burst=20lets a client exceed the average by up to 20 requests. The default burst is zero.nodelayserves burst requests at once instead of spacing them out. Without it, nginx delays excess requests to hold the rate.limit_req_status 429changes the rejection code. The default is 503, which looks like an outage to a client, so set 429 explicitly.
Run limit_req_dry_run on; first. In that mode requests are not limited but nginx counts the excess, and the $limit_req_status variable shows what would have been rejected. Log it for a few days and you will see which real clients your numbers would hit.
The proxy keys by IP in this example. The nginx key can contain variables, so you can key on a header, but per-customer limits tied to your plans are easier to write in application code.
Step 4: add a per-customer limit in code
A token bucket gives each key a bucket that refills at a steady rate. A request spends one token, and an empty bucket means a 429. Stripe's docs suggest the same algorithm for clients that need to throttle themselves.
type Bucket = { tokens: number; updatedAt: number };
const buckets = new Map<string, Bucket>();
export function allow(key: string, ratePerSec: number, burst: number) {
const now = Date.now();
const b = buckets.get(key) ?? { tokens: burst, updatedAt: now };
const refill = ((now - b.updatedAt) / 1000) * ratePerSec;
b.tokens = Math.min(burst, b.tokens + refill);
b.updatedAt = now;
const ok = b.tokens >= 1;
if (ok) b.tokens -= 1;
buckets.set(key, b);
const retryAfter = ok ? 0 : Math.ceil((1 - b.tokens) / ratePerSec);
return { ok, retryAfter };
}
This version keeps state in memory, which works for one server process. Once you run two instances, move the counters into a shared store such as Redis, or each instance will allow its own full rate. Your plan tiers then become a lookup: free keys get 5 requests per second, paid keys 25.
Step 5: return a response clients can use
On a rejection, send status 429 and a Retry-After header. MDN describes 429 as the response for a client that has sent too many requests in a given time, with Retry-After indicating how long to wait. RFC 9110 defines the header's value as either an HTTP-date or a number of seconds, and a number of seconds is simpler to produce.
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json
{"error":"rate_limited","message":"Limit is 25 requests per second. Retry in 2 seconds."}
Stripe adds a Stripe-Rate-Limited-Reason header that says whether the global rate, an endpoint rate or a concurrency limit was hit. Naming the limit that fired saves your customers a support ticket. Document the limits in your API docs, with a short example of a retry loop that uses exponential backoff with random jitter, which Stripe recommends to avoid a thundering herd.
There is also an IETF draft for RateLimit and RateLimit-Policy response headers that report remaining quota. Version 11 was published in May 2026 and is still an active Internet-Draft that expires on 24 November 2026, so treat the field names as provisional. Sending your own X-RateLimit-* headers or the draft's names is optional. Retry-After is the one clients will reliably understand.
Step 6: test it
- Fire 100 requests in a loop against a staging route and confirm the first ones pass and later ones return 429.
- Check that
Retry-Afteris present and that waiting that long lets the next request through. - Confirm webhooks from providers you rely on are not caught by an IP limit. A payment provider that retries a failed webhook should not be blocked by you. See how to test Stripe webhooks locally for a safe way to replay events.
- Alert on a sudden rise in 429s. It means either an attack or a limit set too low.
Frequently asked questions
What is the difference between rate limiting and throttling?
Rate limiting rejects requests above a threshold, usually with a 429. Throttling slows them down instead. The nginx limit_req module does both: it delays requests up to the burst size, and rejects those beyond it, unless you set nodelay.
Which status code should a rate-limited API return?
Return 429 Too Many Requests, defined in RFC 6585, with a Retry-After header. nginx's default rejection code is 503, so set limit_req_status 429 explicitly.
Should I rate limit by IP address or API key?
Use the API key for authenticated routes and the IP address for anonymous ones such as login. Using IP alone punishes customers who share an office network, and using the key alone leaves public routes open.
Do I need Redis for rate limiting?
Only when you run more than one app instance. With one process, an in-memory token bucket is enough. With several, each instance would otherwise count separately, so shared counters in Redis or similar are needed.