From reading to action
A practical path through this guide.
Select a step to explore what to do and why it matters.
Classify the response
Separate temporary pacing failures from permanent data and access errors.
A useful retry strategy distinguishes temporary failures from requests that need correction. Retrying every error quickly can overload a dependency and increase costs. Build a bounded policy around the provider's documented response and the safety of repeating the operation.
Classify before retrying
A rate-limit response may be recoverable after waiting. A malformed field generally needs a mapping or data fix. An authorization error may require reconnecting an account. A timeout on a write has an uncertain outcome and needs deduplication or reconciliation before another attempt.
Avoid assuming every server error is safe to repeat. A provider might complete a write before returning an error through a proxy. Use supported idempotency keys or inspect the destination by business identifier when the result is unclear.
Respect the provider's pacing
Use a documented retry delay when available. Otherwise apply a capped increasing delay with jitter, a maximum attempt count, and a maximum elapsed recovery window. Keep these configurable so a change in provider policy does not require rebuilding the whole workflow.
If multiple workers share one account quota, independent retry loops can collide repeatedly. Coordinate request throughput at the account boundary. Track both request rate and concurrency because a limit on simultaneous work behaves differently from a per-minute allowance.
Prevent backlog spirals
Separate new intake from retry work. Give both queues visibility and avoid letting one bad record block all subsequent records unless ordering requires it. After the retry budget is exhausted, move the item to an exception queue with an owner.
A useful alert includes the dependency, status class, affected record reference, next retry time, and final escalation point. It should not include credentials or a complete customer payload. Group repeated failures during one vendor incident.
Test the policy deliberately
Simulate a rate limit, a transient timeout, a permanent validation error, and a recovery after several failed attempts. Inspect spacing between attempts and verify that the maximum is enforced. Confirm that one source event still causes only one business effect.
Measure retry rate after launch. A permanently elevated retry count can indicate that normal throughput exceeds the provider's capacity or that the polling design is wasteful. Increasing the retry budget may hide the underlying mismatch while making recovery slower.
Further reading
HubSpot's API usage guidelines illustrate why limits must be checked for the actual account and API. See workflow monitoring for backlog signals.
A few practical answers
Frequently asked questions
Should every failed API request be retried?
No. Classify the failure first. Malformed data or missing permissions generally needs repair, while a temporary rate limit may recover after appropriate pacing.
What makes a retry policy bounded?
Set a maximum attempt count and recovery window, use capped delays with jitter where appropriate, and route exhausted work to an owned exception queue.
