Handling Rate Limits

Why limits exist

A shared API protects itself and every other consumer by capping how many requests one client may make in a window. Rate limits prevent a single misbehaving integration from starving everyone else, and they keep costs and capacity predictable.

Limits are usually expressed as requests per second, per minute, or per day, sometimes per endpoint and sometimes per credential. Hitting the limit is not an error in your code so much as a signal to slow down. A well-behaved client treats limits as a normal part of the contract, not an exception to be ignored. Plan your traffic around the budget rather than discovering it under load.

Reading the signals

Most APIs tell you where you stand through response headers. Common conventions include a remaining count and a reset time:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1751155200

Use these proactively. If Remaining is low, slow your sending before you are blocked rather than after. When you do exceed the limit, the server responds with 429 Too Many Requests, often accompanied by a Retry-After header telling you how long to wait. Reading these signals lets a client self-regulate instead of blindly retrying into a wall, and it turns the limit from a surprise into a number you can plan around. Treat the headers as the authoritative source rather than guessing your remaining budget from a local counter.

Reacting to a 429

When you receive a 429, stop and wait. If a Retry-After value is present, honour it exactly — it is the server telling you when capacity returns. If it is absent, fall back to exponential backoff with jitter.

• Do not retry immediately — that simply earns another 429.
• Pause the whole client, not just one request, if the limit is account-wide.
• Queue work and drain it at a sustainable rate.

Treating a 429 as a hard stop, not a soft suggestion, is the difference between recovering smoothly and being locked out for longer.

Staying under the cap

The best rate-limit handling is avoiding the limit. Smooth out bursts by spacing requests evenly rather than firing them all at once. A simple token-bucket or leaky-bucket approach lets you cap your own send rate locally.

For bulk work, process in batches with a short pause between them, and prefer endpoints that return many records per call over many calls returning one record each. Cache responses that rarely change so you are not re-fetching the same data. If you regularly bump the ceiling, that is a sign to redesign the access pattern — or request a higher quota — rather than to retry harder.