Rate Limits: The Rush-Hour Rules
Friday, 17:40. Rides are ending all over Riverport, the map is repainting every few seconds, and Vera is running her five-page station sweep for the third time in two minutes because she keeps spotting a number she wants to check. Then a response comes back that is not a station list: 429 Too Many Requests.
Sixty requests a minute is Tandem's posted speed limit for one key. A rate limit is exactly that: a cap on how often you may ask, counted over a short window. The counters have been riding along in every response since Chapter 3, and this page turns the book's canonical traffic jam into technique.
Why the Limit Exists
Tandem's API serves the rider app, the city, tourism boards, researchers and Vera from the same machines. Without a cap, one enthusiastic caller with a fast loop could crowd out everyone else — not maliciously, just by asking faster than the others. The limit is how the provider keeps one guest from taking the whole buffet, and Chapter 5 promised exactly this when it explained why an API wants to know who is calling: a key is the unit that fairness is counted against.
It protects you too, in a way that is easy to miss. The limit is what stops a mistyped loop from turning into a bill, a blocked key, or an apologetic phone call. Vera-of-five-minutes-ago, sweeping the same five pages three times over, was being throttled on behalf of Vera-of-five-minutes-from-now.
The Counters Were Always There
An API that enforces a limit almost always tells you where you stand, in the response headers, on every single response — the successful ones included. Three ideas travel together: the ceiling, how much of it you have left, and when the count starts over.
Tandem spells them X-RateLimit-Limit, which is 60; X-RateLimit-Remaining, which counts down toward zero as you spend the minute; and X-RateLimit-Reset, saying when the window rolls. Header names vary from API to API — some use different prefixes, some pack all three into one line — but the trio of ideas is near-universal, and the documentation names the exact spellings. Add -i to any curl command you have run since Chapter 3 and they are there, and always were.
Reading them before you hit zero is the actual skill. Remaining is a fuel gauge: the professional habit is glancing at it as a matter of course, not discovering it in the middle of an outage.
The 429 and the Polite Recovery
A 429 is a 4xx, so by Chapter 7's rule the problem is on your side — and it is, in the narrow sense that you sent the requests. But it behaves unlike every other 4xx you have met. A 401 needs a key, a 404 needs a corrected path, a 422 needs a fixed value. A 429 needs nothing except time.
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Reset: 1787938860
X-RateLimit-Remaining: 0
{"error": {"code": "rate_limited",
"message": "Too many requests. Try again in 30 seconds.",
"request_id": "req_4a71"}}
The response says everything needed: nothing about the request was wrong, the allowance is spent, and here is how many seconds until it is not. Honor that number. Waiting the stated time and then continuing is the entire correct response, and it works.
If the 429 comes back again after you resume, the rule is the one Chapter 7 gave for a struggling server, and it is simple enough to state in one sentence: wait, and wait longer each time. Twenty seconds, then forty, then eighty — the backoff from the last chapter, now aimed at a full window. A queue clears when the traffic eases, never when it doubles. Retrying instantly and repeatedly is the one behavior that turns a temporary refusal into a key that providers start noticing.
The everyday shape of this is the café at rush hour with a "one order per visit to the counter" sign. It is not hostility; it is throughput, and it exists because the alternative is a scrum in which nobody gets coffee. Regulars glance at the queue before they walk over, and they time their trips. The barista does not remember the people who waited. She remembers the one who kept barging in.
Designing Under the Ceiling
Sixty a minute sounds tight until you count what the Thursday report actually needs. Three moves bring almost any honest task comfortably under any sane ceiling, and this chapter is quietly a tour of all three.
Space the requests. Five pages fetched a second apart cost the same five requests as five fetched at once, and never approach the ceiling. Filter harder — the previous topic turned five requests into one by asking a narrower question, which is the largest saving available to anyone. And do not re-ask for things that have not changed, which is the whole subject of the next page.
Asked this way, the Thursday report fits in about a dozen requests and never sees a 429 again. That is the honest summary of the whole page: the limit was almost never the problem. The questions were.
- "A 429 means my key is being punished." It means this minute is full. The window resets on a published schedule and no apology is required — unless the hammering continues, which is genuinely how keys end up on somebody's list.
- "The limit is per endpoint, or per computer." It is typically per key, across everything that key calls, and the docs state the unit. Two of Vera's terminals share one budget, which is a much better surprise to meet on this page than at 17:40 on a Friday.
- "Remaining: 3 means something is wrong." It means the gauge is working. A low reading is information, not an error, and the response it calls for is slowing down rather than pretending you did not see it.
- "Retry-After is a suggestion, so a quick retry is fine." It is the provider telling you exactly when the answer changes. Asking before then wastes a request, which is counted, and can extend the wait rather than shorten it.
- Reading the headers, honoring Retry-After, and backing off are the etiquette half of being a good guest at someone else's counter. Providers do notice, and the partners who never get throttled are the ones whose access requests get approved fastest.
- The three moves that keep you under the ceiling are the same three that make the report fast. Space, filter, and reuse what you already have: the polite way and the fast way are the same way.
Knowledge Check
A response carries X-RateLimit-Limit: 60 and X-RateLimit-Remaining: 3. What do they say?
- Three seconds remain before the current request times out
- Sixty requests are allowed this window and three remain
- Sixty partners share the API and three of them are active
- Sixty requests succeeded today and three of them failed
You get a 429 with Retry-After: 30. What is the correct response?
- Send the request again immediately in case that one gets through
- Check the address and the parameters for the mistake in them
- Wait the thirty seconds it names, then resume at a gentler pace
- Email Jonas for a second key so the work can continue now
Two of Vera's terminals both run sweeps with the same key. What happens to the budget?
- Each machine gets its own sixty, since the limit counts devices
- Each endpoint gets its own sixty, so the two never collide
- They share one allowance and reach the ceiling twice as fast
- The second terminal is queued until the first one has finished
Which change most reduces the chance of hitting the limit at all?
- Retrying faster so more requests land before the window resets
- Asking a narrower question so fewer requests are needed
- Raising the page size far past the documented maximum
- Ignoring the headers until a 429 actually arrives
You got correct