Why Your API Rate Limits Are Lying to You
The documentation says 1000 requests per minute. You hit an error at 400. You check the docs again. Still says 1000. You're not crazy — the limit is real, but it's not the limit you think it is.
Rate limiting is one of those areas where the gap between documentation and reality is consistently wider than it should be. I've spent more time than I'd like debugging rate limit behavior across different APIs, and the patterns are predictable once you know what to look for.
The Three Limits You're Actually Dealing With
Most APIs have at least three separate rate limits operating simultaneously. The one in the docs is usually the per-minute or per-hour limit on total requests. But there's also a per-second burst limit — often undocumented — that kicks in when you make requests too quickly even if you're under the per-minute ceiling. And there's frequently a per-endpoint limit that's different from the global limit.
The burst limit is the one that gets people. You're making 400 requests per minute, well under the 1000 limit, but you're making them in batches — 50 requests in 2 seconds, then nothing for 10 seconds. The burst limit sees 50 requests in 2 seconds and throttles you. The per-minute counter sees 400 and thinks you're fine. You get errors that don't make sense.
The folks at developer culture have been writing about this kind of undocumented behavior — the gap between what APIs say they do and what they actually do under load.
How to Actually Test Your Limits
Don't trust the documentation. Test it. Start with a simple script that makes requests at a controlled rate and logs the response headers — most APIs return rate limit information in headers even when they don't document it. Look for X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After.
Then test burst behavior separately. Make 10 requests in 100ms. Make 50 in 500ms. See where the errors start. The burst limit is usually somewhere between 10 and 50 requests per second, but it varies wildly.
The API design patterns discussion has some good material on how to structure retry logic once you know your actual limits — exponential backoff with jitter is the standard answer, but the parameters matter.
The Shared Limit Problem
If you're using a third-party API through a platform or aggregator, your rate limit might be shared with other users of that platform. You can be well under your documented limit and still get throttled because someone else on the same API key pool is hammering the endpoint.
This is more common than it should be, and it's almost never documented. The only way to know is to test at different times of day and see if your effective limit changes.
More on this at josephcalitoy.com — there's a piece coming on how we handle rate limiting across the Calitoy infrastructure. And the Calitoy Core archive has more on systems thinking for builders.