Skip to content
API Design Learn/Production REST I: Performance & Reliability
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Rate Limiting

4 min read

You'll learn to

  • -Tell clients their limit with X-RateLimit headers on every response, not only the refusal
  • -Answer an over-limit request with 429 and Retry-After, never silence
  • -Run a blind client and a polite one against the same limit and compare the wasted requests

Rate limiting protects a service from being overwhelmed by any one client. The algorithms for counting requests are in the LLD rate limiter chapter. This chapter covers the API-design half: how the limit is communicated to callers. An API that rejects requests without explanation forces every client to find the limit by trial and error.

An Analogy: The Busy Cafe's Order Counter

A busy cafe tells you "five orders per customer per ten minutes". If the sign is up where you can see it, and the barista says "that is your fourth, one left", you plan your order. If the barista just stares at you, you cannot tell whether they are ignoring you, whether the till is broken, or whether you are over your limit. Headers are the sign and the barista's running count.

Conventional Rate Limit Headers

The X-RateLimit-* headers below are a widely used convention (GitHub, Stripe and many others use this shape), not a ratified HTTP standard. A newer official RateLimit header field exists, without the X- prefix, but the X-RateLimit-* form is what you will see at most companies, and it is safe to use in an interview if you call it a convention.

Telling the client exactly where it stands before it gets rejected
GET /orders
HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 37
X-RateLimit-Reset: 1735689600
  • -X-RateLimit-Limit: the total requests allowed in the current window.
  • -X-RateLimit-Remaining: how many requests are left before throttling.
  • -X-RateLimit-Reset: when the window resets, as a Unix timestamp (seconds since 1 January 1970), so the client knows how long to back off.

Send these on every response, not only the one that is finally rejected. A well-behaved client can then slow down as Remaining approaches zero, instead of firing at full speed until it hits a wall.

429 Too Many Requests, With Retry-After

An explicit rejection with a concrete retry time
GET /orders
HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1735689600

{"error": "Rate limit exceeded. Retry after 42 seconds."}

Retry-After, in seconds or as an HTTP date, tells the client exactly how long to wait. That is strictly better than a guess: too short a guess hits the limit again at once, too long wastes time the server would have accepted the request.

The demo compares two clients against a limit of 5 requests per 10 seconds, each sending 8. The blind client ignores headers. The polite client reads Remaining on every response and waits when it reaches zero.

Press Run: the blind client is refused 3 times, the polite client never is

Silently dropping requests once the limit is hit, with no reply or a generic timeout, is worse than an explicit 429. It leaves the client unable to tell "I am being rate limited" from "the server is down", which leads to the wrong recovery in either case.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design Rate Limit Fortress in the API Design Lab's Production Patterns act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!