API rate limiting definition
API rate limiting is the practice of capping how many requests a client can make to an API within a fixed window of time, and rejecting or deferring requests that exceed the cap. Limits are expressed as a count per unit of time (requests per second, minute, or hour) and scoped to an identity the server can attribute traffic to, such as an IP address, API key, account, or project.
API rate limiting caps how many requests one client can send to an API in a given window, returning an error such as HTTP 429 once the cap is passed, so a single noisy caller cannot exhaust capacity for everyone else. Sanity draws the line at the cache boundary: cached responses from the API CDN are not rate limited, and only cache misses reach the direct Content Lake API, where a 500 requests-per-second-per-IP ceiling and per-dataset concurrency ceilings apply.
APIs use rate limiting to keep one client's traffic from degrading service for every other client. As MDN puts it, rate limiting means "controlling how many operations can be performed in a given amount of time, usually to avoid overloading the system and causing performance degradation."
Beyond protecting backend capacity, API rate limiting contains the blast radius of a buggy client stuck in a retry loop, mitigates abuse such as denial-of-service attempts and credential stuffing, enforces fair use across tenants sharing the same infrastructure, and makes spend predictable on metered services.
There is a second benefit that matters to the people calling the API rather than the people running it. A published limit is a number you can design against. If you know a read endpoint allows a certain number of requests per second per IP, you can decide up front whether to batch calls, cache responses, or queue work, instead of discovering the ceiling during a traffic spike.
When you exceed an API rate limit, the server typically rejects the request with HTTP 429 Too Many Requests. The status code is defined in RFC 6585, section 4, published in April 2012, which says it "indicates that the user has sent too many requests in a given amount of time ('rate limiting')" and that the response may include a `Retry-After` header telling the client how long to wait.
It helps to keep the policy and the signal separate. The rate limit is the rule; the 429 is one way of announcing that you hit it. An API can enforce a limit without ever returning 429, by queueing requests, shedding them silently, or answering with a 503, and a 429 can in principle be returned for reasons other than a documented per-client cap.
Response headers such as `X-RateLimit-Limit` and `X-RateLimit-Remaining` are widespread convention rather than a standard. The IETF effort to formalize them, RateLimit header fields for HTTP, is still an Internet-Draft and has not been published as an RFC, so treat the headers as something an individual API may or may not send.
API rate limiting is enforced with a counting algorithm that decides, for each incoming request, whether the client's recent traffic is under the cap. Four algorithms cover almost everything you will meet in practice.
The token bucket holds a bucket of tokens that refills at a fixed rate. Each request spends one token, and a request with no token available is rejected. Because the bucket has depth, short bursts are allowed while the long-run average stays capped. Amazon API Gateway is one widely used implementation of the approach.
The leaky bucket queues requests and drains them at a constant rate, smoothing traffic rather than passing bursts through. The fixed window counter keeps one counter per calendar window, which is cheap to run but lets a client fire a full window's worth of requests on either side of a boundary, briefly doubling the intended rate. The sliding window, kept either as a log of request timestamps or as a weighted counter blending the current and previous windows, removes that boundary effect at the cost of more state to track.
These four terms are related but not interchangeable, and confusing them is the usual cause of an integration that passes testing and then fails in production.
Rate limiting and throttling are often used as synonyms. MDN states that rate limiting is "typically synonymous with throttling." Where writers do draw a line, the distinction is reject versus delay: rate limiting turns excess requests away, while throttling slows or queues them. That distinction is a useful shorthand rather than a settled standard, so check what a given API actually does.
A quota is about volume over a billing or entitlement period, usually a month, while a rate limit is about speed in a window that resets continuously. You can sit comfortably inside a rate limit and still exhaust a monthly quota, and the consequences differ: a breached rate limit usually produces a 429 on the next call, while a breached quota triggers overage billing, degraded service, or a hard stop.
A concurrency limit counts requests in flight at the same moment, regardless of how fast they arrived. Ten requests per second that each take sixty seconds to finish will breach a concurrency ceiling of 100 long before they trouble a rate limit of 500 per second. Load shedding is different again: it is a reactive response to actual saturation, usually not per client and usually not published, where a rate limit is a pre-declared contract that applies whether or not the system is under stress.
Sanity publishes its Content Lake API limits, enforces them with HTTP 429, and keeps cached reads out of the counted path entirely. The technical limits documentation sets a global ceiling of 500 requests per second per client IP, with 25 requests per second per IP for mutations (`POST` to `/data/mutate` and `/data/actions`) and 25 per second per IP for asset uploads (`POST` to `/assets/`). Per dataset, concurrency ceilings allow 500 concurrent queries, 100 concurrent mutations, and 5 concurrent exports. Exceeding a limit returns 429 for further requests of that type until the next period begins.
The API CDN is the architectural answer rather than a restatement of the problem. Requests to `apicdn.sanity.io` that hit the cache are not rate limited; only cache misses are forwarded to the direct API at `api.sanity.io`, where the rate and concurrency ceilings apply. Pointing read traffic at the cache with the `useCdn` client option therefore shrinks the volume of traffic being counted at all.
On the client side, `@sanity/client` retries 429, 502, and 503 responses on `GET`, `HEAD`, and `/data/query` requests, five times by default, with exponential backoff of `100 * 2 ** attemptNumber` milliseconds plus up to 100 milliseconds of jitter. Mutations are deliberately not retried: `create()`, `patch()`, `delete()`, transaction commits, and asset uploads surface a 429 to your code immediately, because silently repeating a write is riskier than failing loudly.
That combination reflects how Sanity works as a Content Operating System for the AI era. Delivery limits are documented numbers rather than hidden thresholds, so teams building websites, apps, and AI agents on the same content can plan traffic against a contract they can read.
Explore Sanity Today
Understanding API rate limiting is just the beginning. Take the next step and discover how Sanity can enhance your content management and delivery.
Last updated: