unkey
  • BlogRead product updates and insights
  • Case studiesPractical results from real deployments
  • ChangelogTrack what shipped, improved, and fixed
  • GlossaryClear definitions for API terms
PricingDocs
Discord
LoginSign Up
  • BlogRead product updates and insights
  • Case studiesPractical results from real deployments
  • ChangelogTrack what shipped, improved, and fixed
  • GlossaryClear definitions for API terms
PricingDocsDiscord
LoginSign Up
  1. Glossary
  2. /Rate Limiting

What Rate Limiting Is

Explore with AI
Open in ChatGPTOpen in ClaudeOpen in Perplexity

TL;DR

Rate limiting counts a caller's requests and rejects new ones once the caller passes a cap for that interval. The usual HTTP status is 429, with Retry-After telling the client how long to wait. To limit per customer or per API key, count on the customer id or the key id in a store every server shares.

Cap

A count per caller and interval

Over the cap

Reject the request

Usual status

429 Too Many Requests

Rate limiting is how an API caps how many requests a client can make in a set time. The API counts calls for that client. Under the cap, the call proceeds. Over the cap, the API rejects it, usually with 429 Too Many Requests.

To rate limit an API per customer or per API key, count on the customer id or the key id, keep that count in a store every server shares, and send 429 with Retry-After when it runs out.

The cap protects capacity. It keeps one client from crowding out the others, and it bounds work you pay another system to do. OWASP API4 describes what happens when that bound is missing: the API spends CPU, storage, or money on whoever sends the most traffic.

How do you rate limit an API per customer or per API key?

A key limit counts each API key on its own. Three keys at 100 requests a minute is 300 a minute. That fits a key with its own job, like a partner integration that syncs data in bulk.

A customer limit counts every key the customer holds against one number. Three keys, 100 requests a minute, shared. If you limit only per key, a customer who creates a second key doubles their quota. Most APIs that sell access want the customer limit as the default and a key limit as the exception.

To count per customer, store the customer id on every key record. On each request, look up the key, read its customer id, and increment the counter named by that customer id. Every key that customer holds then draws from one count. A key that needs its own number gets a second counter named by the key id.

// counter is any store every server shares: Redis, a database row, or a rate limit service.
async function checkLimit(counter, key, limit, windowMs) {
  const name = key.limitPerKey ? `key:${key.id}` : `customer:${key.customerId}`;
  const windowStart = Math.floor(Date.now() / windowMs) * windowMs;
  const count = await counter.increment(`${name}:${windowStart}`, windowMs);

  if (count > limit) {
    const retryAfter = Math.ceil((windowStart + windowMs - Date.now()) / 1000);
    return { allowed: false, retryAfter: Math.max(1, retryAfter) };
  }
  return { allowed: true };
}

increment has to be atomic in the shared store, such as INCR with an expiry in Redis. Read then write from two servers at once and both see the old count.

When a customer upgrades, change the number you look up for that customer. Keep limits in data, not in code, so a plan change needs no deploy.

How do you add rate limiting to a Next.js or Express API?

To add rate limiting to a Next.js or Express API, run one check before your route code. Name the caller by API key, then user id, then IP. Check a counter every instance shares, and return 429 with Retry-After when it runs out.

Keeping the count out of the process is the important part. In Express, the express-rate-limit middleware keeps its count in process memory by default. Each server instance enforces its own copy of the limit, so the real cap grows with the instance count. The package accepts an external store, such as Redis, to share the count. Next.js route handlers on serverless functions have the same problem, and a cold start begins with an empty count.

In Next.js, put the check in middleware when every route shares one limit, or at the top of the route handler when routes need different limits. In Express, mount the middleware before the routes it protects. Behind a proxy you run, set trust proxy so the IP is the client and not the proxy.

How do you rate limit across multiple servers or regions without Redis?

The counter has to live outside your processes. If you don't want to run Redis, use a hosted rate limit service, the rate limiting built into a CDN or API gateway you already use, or a database you already run.

A counter in process memory applies once per process, so two servers each enforcing 100 requests a minute allow 200. The usual fix is a shared Redis. Then you run Redis, size it, watch it, and add a network round trip to every request.

Across regions, an exact global count means every request waits on one place. Most multi-region limiters keep a counter in each region and share counts between regions in the background. The counts are close, not exact. When one region receives most of a caller's traffic, enforcement is tight. When traffic is split across regions, a short burst can get through in more than one region before the counts catch up. If you need an exact total, such as a monthly quota, keep it as a separate counter that a single store owns.

Ways to rate limit an API compared

ApproachWhere the count livesSame limit on every serverPer customer across keysWhat you run
In-process counter, such as express-rate-limit with its default storeEach processNoYou build itNothing extra
Redis-backed limiterA Redis instanceYesYou build it, keyed by customer idRedis, hosted or your own
API gateway or CDN rate limit ruleThe gateway or CDNDepends on how it shares countersDepends on the productThe gateway, or nothing if the CDN is already there
Hosted rate limit serviceThe providerYesDepends on the serviceOne API call per request

A gateway rule is a good answer when you already run that gateway. A Redis limiter is a good answer when you already run Redis and want to own the code. The in-process counter is fine for one process and a prototype.

Fixed windows

A fixed window counts requests in a bucket that resets on a clock. "100 per minute" can mean one counter per client per minute.

const hits = new Map();

function allow(clientId, limit, windowMs, now = Date.now()) {
  const windowStart = Math.floor(now / windowMs) * windowMs;
  const id = `${clientId}:${windowStart}`;
  const count = hits.get(id) ?? 0;

  if (count >= limit) {
    return false;
  }

  hits.set(id, count + 1);
  return true;
}

The first limit calls in a window return true. The next call returns false until windowMs rolls forward. In Node.js this function is safe against interleaving only because it never waits: one process runs it to completion before another call starts. Two API processes each have their own Map. Each enforces limit, so the real ceiling is limit times the number of processes.

A client can also send limit requests at the end of one window and limit at the start of the next. That is twice the advertised rate across a few milliseconds. A sliding window, which weighs the previous window into the current count, closes that gap. With a limit of 100 per minute, a caller who made 100 requests at the end of one minute still counts as 75 fifteen seconds into the next, so the burst can't repeat right away.

The map needs eviction. Each window creates a new id, and old ids stay in memory until you delete them.

Token buckets

A token bucket holds tokens up to a capacity. Each allowed request takes one token. Tokens return at a steady rate. The capacity is the burst. The refill rate is the sustained rate.

function createTokenBucket(capacity, refillPerSecond) {
  let tokens = capacity;
  let updatedAt = Date.now();

  return function take() {
    const now = Date.now();
    const elapsedSeconds = (now - updatedAt) / 1000;
    tokens = Math.min(capacity, tokens + elapsedSeconds * refillPerSecond);
    updatedAt = now;

    if (tokens < 1) {
      return false;
    }

    tokens -= 1;
    return true;
  };
}

A bucket created as createTokenBucket(20, 10) allows a burst of 20, then about 10 requests per second while the caller keeps going. Empty means reject until a token returns. This sketch has the same single-process limit as the fixed window. Nothing here coordinates two servers.

A shared store makes the count global. That store is another network call on the request path, and it can fail. Choose the failure mode before it happens. Fail closed rejects requests when the counter is unreachable, which protects the API and can take the API down with the counter. Fail open allows requests, which keeps the API up and can overload it. Neither choice is free.

Who the limit names

Prefer the credential. An API key already identifies the integration, so a limit on that key id matches the caller you issued. A customer id is the right key when the company, not one integration, is the quota. A user id is right when the person is the quota.

An IP address is a fallback for anonymous traffic. It is a poor primary key. Carrier gateways and offices share one address, and a single client can spread across many. Behind a reverse proxy, the socket address is the proxy. The original client may be listed in X-Forwarded-For. Trust that header only when the immediate peer is a proxy you run. A client can put any address in the header, and appending your own observation is the proxy's job.

Routes can have separate buckets. A login attempt and a cheap health check should not draw from the same quota. Limit the thing that is scarce. A cap on health checks does nothing for a database that melts under search traffic. An expensive route can also count as more than one request.

API keys, rate limits, and hosting together

Adding API keys and rate limiting to a hosted API often means a host, a key store, a Redis instance, and middleware to glue them together. You need fewer pieces when one layer does both checks.

Some API gateways and hosting platforms check the API key and apply the rate limit before the request reaches your code. A key service that also enforces limits during verification does the same job from inside your handler.

What the client receives

RFC 9110 defines 429 Too Many Requests. RFC 6585 is where that status was introduced. Retry-After says how long to wait. The value is either a number of seconds or an HTTP date. MDN's 429 page summarizes the same behavior for clients.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{"error":"rate_limited"}

Many APIs also send a vendor header such as X-RateLimit-Remaining. The name is a convention, not a standard, and products spell it differently. The IETF RateLimit header draft defines RateLimit and RateLimit-Policy. As of 2026 it is still an Internet-Draft, so the field syntax can change before it becomes an RFC. Clients can rely on the status code and on Retry-After. Treat other limit headers as hints.

Clients that retry immediately undo the limit. They fill the bucket again and add load. Honor Retry-After, add a little random jitter, and retry a write only when sending it twice is safe.

Neighbors, and the tradeoff

A load balancer chooses which instance gets the next request. It does not cap one client. A circuit breaker stops this service from calling a dependency that is already failing. A rate limit stops callers from exhausting this service. The three sit next to each other because they answer different questions.

A tight limit rejects real traffic during a launch or a retry storm. A loose limit does not protect the scarce resource. Put the number on the thing that runs out first, measure how often legitimate clients hit it, and raise the cap when the rejections are the problem. The counter you configured is not the cap users experience until every accepting instance shares that counter.

Rate limiting with Unkey

Unkey runs rate limiting as a hosted service. You can put a limit on an API key or on a customer, and every key that customer holds shares it. keys.verifyKey checks the limit on each request, and ratelimit.limit counts any identifier, such as a user id or an IP. Unkey keeps the counters, so you don't run Redis. The rate limiting docs show each option.

Questions & Answers about Rate Limiting

Rate limiting caps how many requests a client can make in a set time. The API counts calls for that client. Under the cap, the call proceeds. Over the cap, the API rejects it, usually with HTTP 429, until the window or the token bucket allows another call.

On this page

  1. How do you rate limit an API per customer or per API key?
  2. How do you add rate limiting to a Next.js or Express API?
  3. How do you rate limit across multiple servers or regions without Redis?
  4. Ways to rate limit an API compared
  5. Fixed windows
  6. Token buckets
  7. Who the limit names
  8. API keys, rate limits, and hosting together
  9. What the client receives
  10. Neighbors, and the tradeoff
  11. Rate limiting with Unkey

Turn your API stack into one workflow. Start for free, integrate in minutes, and scale when you need to.

Start for free
unkey

Build better APIs faster

© 2026 Unkey Inc. All rights reserved.

SOC 2 Type II Certified

Company

  • About
  • Careers
  • Status Page
  • Roadmap

Resources

  • Blog
  • Case Studies
  • Changelog
  • Docs
  • Glossary
  • Feature Request
  • Archive

Connect

  • X (Twitter)
  • Discord
  • Book a Call

Legal

  • Terms of Service
  • Privacy Policy
  • Trust Center