Rate Limits and Retries
You wired up an API call, it worked, you shipped it. Then traffic grew, or the upstream had a bad
minute, and suddenly your logs are full of 429 and 503 — and your "fix" of retrying in a tight loop
somehow made everything worse. That sinking feeling, where the thing meant to help is now the thing
hurting you, is exactly what this guide clears up.
Here's the relief: calling a flaky or throttled API well is a small, learnable set of habits, not a dark art. APIs rate-limit you on purpose, and they tell you how to behave — you mostly need to listen. And retrying safely is a handful of rules: wait longer each time, add a little randomness, cap how hard you try, and never blindly retry something that moves money. Learn those, and a wobbly dependency becomes a minor annoyance instead of a 2am page.
How to read this
- Mid-incident, need the rule right now? Phase 2 has the backoff-and-jitter recipe and the "is this safe to retry?" checklist; Phase 3 has the circuit-breaker idea for when a dependency is truly down.
- Want it to actually make sense? Read in order. Phase 1 explains why limits exist (so you stop taking them personally), Phase 2 turns retrying into a safe reflex, and Phase 3 covers the failure modes that bite teams who only learned the happy path.
The phases
- Why APIs Push Back — the mental model: rate limits aren't an insult,
they're how a shared service protects itself. Token buckets, the
429status, and theRetry-Afterheader that tells you exactly how long to wait. - Retrying Without Making It Worse — the everyday core: exponential backoff, why you must add jitter, a retry budget so you give up gracefully, and the golden rule of only retrying requests that are safe to repeat.
- When Retrying Isn't Enough — the deeper payoff: the thundering-herd problem, the circuit breaker that stops you from hammering a downed service, and what it means to be a genuinely good client.
This guide stays at the level you need to write a resilient client. The provider's side — designing and enforcing limits, sizing buckets, fairness across tenants — is its own topic; for the broader API picture see REST APIs, Explained and What an API Is.