API Reliability
API Retry and Exponential Backoff Guide
Design API retries with exponential backoff, jitter, attempt limits and idempotency boundaries instead of multiplying an outage. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Classify the failure | Retry connection resets, selected timeouts and documented 429 or 5xx responses, not every error. |
| Protect writes | Use idempotency keys or operation identifiers before retrying create and payment requests. |
| Add jitter | Randomized delay prevents many clients from retrying at the same instant. |
| Stop predictably | Set attempt, elapsed-time and caller-deadline limits. |
Starter snippet
delay = min(cap, base * 2^attempt) + random_jitter
retry only transient failuresReview checks
- Honor Retry-After when the API sends it.
- Record attempt number and final outcome in logs.
- Keep retries below the parent request deadline.
- Test duplicate-write behavior deliberately.
Common mistakes
- Retrying validation and authentication failures.
- Stacking library retries behind proxy retries.
- Using fixed delays across a large fleet.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Api Idempotency Retry Guide, Api Timeout Debugging Guide, Api Rate Limit Debugging.