How to Set API Rate Limits for a Custom SaaS
A practical method for setting SaaS API rate limits that protect uptime without throttling legitimate partners, bulk jobs, or peak integrations.
SaaS API rate limits, the caps on how often a client may call the application programming interface of a software as a service product, work best when set per API key, per endpoint, and per traffic class, a group of requests with similar cost and urgency. API keys identify each integrating system, endpoints are the individual URL paths that expose a function, and HTTP 429 is the standard status code for too many requests. Start from observed usage, allow normal integrations room for short spikes, return 429 responses with retry guidance, and revise the limits after real partner traffic arrives.
Why do fixed request limits break healthy integrations?
A single request-per-minute cap treats a dashboard refresh, a nightly data transfer, and a retry burst as the same load, so the quiet integration gets blocked while the noisy one sets the ceiling.
A rate limit is only useful when it reflects the shape of real traffic. One partner may poll every 30 seconds, another may upload 50,000 records once a night, and a third may retry a failed job. If all three share one number, the bulk job either gets killed or forces the limit high enough that abuse passes through. The result is a support queue full of false positives.
The fix is to separate identity from behavior. Limits on identity answer who is calling; limits on behavior answer what they are calling. You need both, because a generous per-key limit still lets one client hammer an expensive route. Throttling, the act of slowing or rejecting traffic once a cap is reached, should happen at the narrowest useful layer.
What should you rate limit in a custom SaaS API?
Limit authenticated traffic by API key and account, add endpoint-level caps where cost differs, and keep a global circuit breaker, an emergency cap for total traffic, for overload. This mix contains one bad client without punishing shared offices or partners.
An API key is a secret token issued to one integrating system. The account is the customer record that owns one or more keys, users, and data sets. Limit by key first because it isolates a single misbehaving script. Add account caps so one customer cannot exhaust the platform by creating many keys.
Endpoint caps matter when one route is far more expensive than another, such as a report export or a bulk search. An IP address is the network identifier a request arrives from, and many users can share one through a corporate gateway. A global circuit breaker is a last-resort control, not a substitute for per-key limits.
| Limiting dimension | Contains one noisy client? | Protects normal partner traffic? | Operational effort | Best use |
|---|---|---|---|---|
| Per IP address | Weak when many users share one office IP | Poor, because shared networks get blocked | Low | Unauthenticated endpoints only |
| Per API key | Strong | Good when each system has its own key | Low | Default for authenticated traffic |
| Per account | Strong across multiple keys | Good for customer-level fairness | Medium | Plans with several keys per customer |
| Per key and endpoint | Strong | Best for mixed heavy and light routes | Medium | Public APIs with costly endpoints |
| Global circuit breaker | Stops platform overload | Can block everyone if set too low | High | Emergency protection |
The table is a starting point, not a menu to enable all at once. Most young SaaS products need per-key limits plus a few endpoint caps. Add account-level fairness when customers can create multiple keys. Add the global circuit breaker only after you can measure total platform load.
How do you choose the first rate limit numbers?
Use two to four weeks of observed traffic, set the steady limit near the 95th percentile, the level below which 95% of normal calls fall, and add a burst allowance, short-term extra capacity, above it. Leave roughly 20% headroom.
A read endpoint returns data, while a write endpoint changes data or starts work. A starting range for ordinary reads is 1 to 5 requests per second per key, with bursts of 20 to 50 requests over 10 seconds. These are estimates, not universal constants. Writes should usually sit lower, perhaps 0.5 to 2 requests per second, because each call may change stored records or start other work.
A token bucket is a common limiter: it refills credits at the steady rate and lets a client spend saved credits in a short burst. That mechanism handles steady and burst numbers without two separate counters. A fixed window, a limiter that resets a counter on a schedule, is simpler but creates a boundary spike, where a client can send a full allowance at 12:59 and another at 1:00. If you use fixed windows, keep the window short, typically 10 to 60 seconds.
A repeatable setup sequence
To set the first numbers, use a repeatable sequence:
- Record each request with its key, account, endpoint, result, and response time.
- Calculate the p95 for each endpoint and each traffic class, not one number for the whole API.
- Set the steady limit at roughly 1.5 to 2 times the p95 of normal callers, then round down to a number partners can understand.
- Add a burst allowance that lasts 10 to 30 seconds, long enough for a page of records but short enough to stop sustained abuse.
- Set write and bulk limits separately, and document every number in the developer portal.
How do you separate normal integrations from bulk jobs?
Give bulk work a dedicated asynchronous endpoint, which returns before the job finishes, plus a daily quota, a total for the day, while keeping interactive calls on the normal rate limit. This prevents a large import from consuming partner capacity.
A bulk job is any operation that moves or transforms many records in one run, such as a nightly sync, an export, or a backfill; a sync is a scheduled transfer between two systems, and a backfill is a one-time load of historical data. Do not raise the global limit to fit the biggest job, because that gives every client the same capacity. Instead, split traffic into classes, where a traffic class is a group of requests with similar cost and urgency.
Put interactive reads in one class, writes in another, and bulk work in a third. Typically three to five classes are enough for a young SaaS product. A job queue, a holding area for work waiting to run, lets you accept a large request with a 202 response, which means accepted for processing, and process it at a controlled rate. This is a structural choice; if you are still shaping the platform, it belongs in the custom SaaS development scope, not in a later patch.
How should a rate limiter respond when a client hits the limit?
Return HTTP 429 with a machine-readable error code, a Retry-After header, the standard field that states the wait in seconds, and a documented retry policy. Tell the client what limit was hit and how to request a higher quota.
A 429 without guidance creates retry storms. A retry storm is a surge of immediate retries after failures, and it can turn a small limit breach into an outage. Include a machine-readable error code, which is a short fixed string a client can branch on, plus the limit name, the window, the remaining allowance, and a request ID in the body. A request ID is a unique string that lets support trace one call across logs, the records of system events.
Use backoff guidance: backoff means increasing the wait between retries, often with jitter, a small random delay that spreads retries out. If you support writes, require an idempotency key, a unique value that prevents a retried request from creating a duplicate record. For interactive clients, fail fast with a clear error; for batch clients, queue the work and return a job ID. A job ID is a reference the client can use to check progress.
How do you test and revise limits after launch?
Run a staged rollout with roughly 10% of partner keys on new limits for two weeks, compare rejection rates, support tickets, and response time, then widen or adjust before full enforcement. Keep an override path for contracted integrations.
A limit is a product rule, not a setting you deploy once and forget. Review the data weekly during the first month, then quarterly. Watch four signals: rejection rate by key, support tickets that mention 429, p95 response time, and queue depth. Rejection rate is the share of requests turned away; queue depth is the number of jobs waiting.
If a legitimate partner hits the limit regularly, first check whether their client respects Retry-After and backoff. If it does, move them to a higher tier or a dedicated bulk lane. If it does not, document the expected retry behavior and offer a short grace period. Keep a manual override for contracted integrations; an override is a named exception with an owner and an expiry date, not a permanent bypass.
Run capacity checks before raising a limit. A limit increase that pushes stored data load past roughly 70% of tested capacity is a bad trade, even if the API layer looks idle. Limits protect the slowest dependency, the service your product relies on that has the least spare capacity, not just the API layer. The limit is doing its job when ordinary integrations never notice it and broken clients get a clear, fast answer.
Frequently asked questions
What is a good API rate limit for a SaaS product?
There is no universal number. A reasonable starting range for ordinary read endpoints is 1 to 5 requests per second per API key, with a short burst of 20 to 50 requests, then adjust from observed traffic.
Should rate limits be per API key or per user?
Use per API key as the first control because it isolates one integrating system, then add per account caps so a customer cannot multiply capacity by creating more keys. User-level limits are useful for interactive sessions, but they are too narrow for server-to-server integrations.
How do you stop bulk imports from hitting rate limits?
Move bulk imports to an asynchronous endpoint with a job queue and a separate daily quota. Return a 202 response, process the work at a controlled rate, and keep interactive calls on their own limit.
What should a 429 response include?
It should include a machine-readable error code, the limit that was hit, the window, a Retry-After value, and a request ID. Also link to documentation that explains backoff and how to request a higher quota.