An API client that reacts to every failure with an immediate retry can turn a temporary rate limit into a longer outage. The right response to HTTP 429 is not simply “try again.” It is to slow down deliberately, respect the server’s guidance, protect the work already in flight, and make the recovery visible.
Rate limiting is a normal control used to protect shared infrastructure. It can apply to one account, one credential, one endpoint, one IP address, or a broader resource pool. That means an integration can behave correctly in a small test and still fail when several scheduled jobs, webhook handlers, and manual exports run at the same time.
What a 429 response tells you
HTTP 429 means the server believes the client has sent too many requests in a given period. RFC 6585 defines the status code and notes that a response may include a Retry-After header. That header can express a delay in seconds or an HTTP date. HTTP Semantics defines the header format.
A 429 does not necessarily tell you the exact limit. The server may count requests per user, credential, resource, or shared service. It may also use different limits for reads, writes, search endpoints, bulk operations, or expensive reports. Treat the response as a signal that the current request pace is unacceptable, not as a complete description of the server’s policy.
Why immediate retries make the problem worse
Imagine a scheduled CRM sync that launches ten workers. Each worker receives a 429, waits 100 milliseconds, and retries. The workers are still sharing the same credential and destination, so the second wave arrives together and is rejected again. A queue of retries grows while useful work competes with its own recovery traffic.
Three common implementation choices amplify the problem:
- Retrying every error. A malformed request, missing permission, or expired credential will not be fixed by waiting.
- Retrying at the same time. Identical delays cause many workers to wake up together, creating a retry stampede.
- Forgetting what was already accepted. When a timeout occurs after a write, blindly replaying the request can create duplicates unless the operation has an idempotency strategy.
A robust client separates temporary capacity pressure from permanent request errors and from uncertain outcomes. Each category needs a different recovery path.
Build a rate-limit policy before writing retry code
Start with an explicit policy for each integration. Record which endpoints are used, which credentials they share, whether the provider documents quotas, and which operations are safe to retry. Include the expected volume of scheduled work, webhook bursts, backfills, and operator-triggered exports.
Then define the decision for each response class:
- 429: honor
Retry-Afterwhen present, otherwise use bounded exponential backoff with jitter. - 5xx or network timeout: retry only when the operation is known to be safe or can be identified and reconciled.
- 4xx request errors: usually stop and record the request for correction instead of retrying indefinitely.
- 401 or 403: route to token refresh, reauthorization, permission review, or an explicit failure state.
The policy should also specify a maximum attempt count, a maximum elapsed time, and the action taken when the limit is reached. “Retry forever” is not a recovery plan. It is an unbounded workload with no owner.
Honor server timing, then add jitter
When a 429 includes Retry-After, use it as the minimum delay unless your operational policy requires a longer pause. Parse both supported forms: a number of seconds and an HTTP date. Protect the parser from negative, missing, malformed, or unreasonably large values.
When no usable delay is provided, a practical fallback is exponential backoff. For example, a client might wait approximately 1 second, then 2, then 4, then 8, with a maximum delay. Add a small random amount, known as jitter, so separate workers do not resume on the same millisecond.
Backoff belongs to the client that controls the request pace. A shared integration should not let every worker make its own independent decision. Use a queue, shared limiter, or coordinator when multiple processes send through the same credential or endpoint. Otherwise, each worker can be acting reasonably while the combined system exceeds the limit.
Control concurrency, not just request frequency
Rate limits are often described as requests per minute, but concurrency matters too. Ten long-running requests can create pressure even when their average rate looks acceptable. A client should limit both how many requests may be in flight and how quickly new requests are admitted.
Use separate controls for different workloads when the provider allows it. A small urgent webhook update should not wait behind a large historical export, and a backfill should not consume the entire budget needed for normal operations. If the provider offers no separate quota, schedule the backfill, reduce its concurrency, and make its progress resumable.
Pagination deserves special attention. A sync that retrieves hundreds of pages can collide with other jobs even if each individual request is correct. Persist the cursor or page checkpoint, pause safely, and resume from the last confirmed position. Do not restart the entire import after every rate-limit event.
Keep accepted work separate from delayed work
A rate-limited job needs a durable state model. At minimum, distinguish queued, in progress, accepted, delayed, failed, and completed work. Store the endpoint, operation identifier, source record or cursor, attempt count, last response class, next eligible time, and enough diagnostic context to investigate the result.
This state helps prevent two dangerous assumptions. First, a 429 does not mean the underlying business action never happened if the request was a write that timed out or if an upstream system processed it before the response was lost. Second, a successful HTTP response does not prove that a multi-step workflow completed correctly. Use stable operation keys where supported, then reconcile the source and destination after recovery.
For related guidance, see our article on retry logic and queues in digital operations. Rate limiting is one reason a queue exists, but the queue only helps when its states, ownership, and retry rules are explicit.
Make rate limiting observable
Log enough to explain what happened without copying sensitive request bodies into your logs. Useful fields include the integration name, endpoint pattern, credential or account label, response status, retry-after value, calculated delay, attempt number, request or operation ID, queue age, and final outcome.
Monitor more than the count of 429 responses. Track:
- Rate-limit responses by endpoint and credential.
- Requests delayed, abandoned, or permanently failed.
- Oldest queued item and time spent waiting.
- Retry volume compared with successful work.
- Duplicate or reconciliation exceptions after recovery.
- Whether normal scheduled work is being crowded out by backfills or manual jobs.
Alerts should distinguish a short burst from a sustained condition. A single 429 during a provider-side adjustment may need no intervention. A growing queue, repeated exhaustion of retry budgets, or a rising number of business records that have not synchronized does.
Test the recovery path, not just the happy path
A rate-limit test should deliberately return 429 responses with and without Retry-After. Include a numeric delay, an HTTP-date delay, a malformed value, and a delay longer than the client’s maximum. Verify that the client pauses, adds jitter, respects its attempt budget, and records the decision.
Test multiple workers at once. Confirm that a shared limiter prevents a retry stampede and that one delayed job does not block unrelated work forever. Test process restarts while jobs are delayed, because in-memory timers disappear when a worker crashes.
For writes, simulate an ambiguous timeout immediately after the remote service accepts the request. Confirm that the integration uses its operation key, lookup, or reconciliation path before replaying the action. For paginated reads, stop in the middle and verify that the sync resumes from its last confirmed cursor without skipping or duplicating records.
Turn 429 recovery into an operating rule
Rate limiting is not just a loop around an HTTP request. It is a coordination problem involving concurrency, queues, credentials, work priority, durable state, and reconciliation. A reliable integration knows when to wait, when to stop, what work is safe to repeat, and who owns the unresolved items.
DigitalWerks can review an integration’s endpoint usage, concurrency model, retry policy, queue states, operation identifiers, monitoring, and recovery tests. The goal is not to eliminate every 429 response. It is to make temporary capacity pressure predictable, bounded, and recoverable without turning it into duplicate work or silent data loss.