Backoff, jitter and Retry-After: when to retry

A permitted retry still has to wait, and some failures should never be retried at all.

Back to overview

Only retry what can succeed

Pass the HTTP statusCode on each attempt. A failure whose status is not in 408, 425, 429, 500, 502, 503, 504 fails the same way on every attempt. A 400, 401, 403, 404 or 422 won't change on its own, so retrying it only burns budget. retryfuse returns brake with evidence fail and reason non_retryable_status on the first such failure, without waiting for the failure streak.

Full-jitter exponential backoff

When the decision is replay_safe after a failure, the report carries retryAfterMs: a random delay between 0 and min(maxDelayMs, baseDelayMs × 2^streak). Spreading callers across the whole window stops them retrying in lock-step and hitting a recovering service all at once. Defaults are 100ms base and 30000ms cap (policy.baseDelayMs, policy.maxDelayMs). The jitter is seeded from the operation rather than a random source. The same input always gives the same delay, so CI runs are reproducible.

Retry-After is a floor

If the server sent a Retry-After (pass it as the attempt's retryAfterMs), the returned delay is never shorter than that hint. Jitter can only lengthen it, and maxDelayMs still caps it.

Half-open after a cooldown

Set policy.cooldownMs, pass now, and stamp each attempt with at. A circuit tripped by the failure streak stays brake until the cooldown has elapsed since the last failure. After that it goes half-open and admits one probe (circuit_half_open). If the probe fails, the circuit re-opens; if it succeeds, the circuit closes. The budget brake still applies. The engine never reads a clock; you pass now in.

Correctness still comes first

None of this applies to an uncertain write. A post-write timeout returns reconcile_required with evidence unknown whatever its status code or backoff. Waiting longer does not make a possibly-applied effect safe to replay. See why reconcile beats a blind retry and braking a retry storm.