Retry Budget Guard

A retry decision governed by a BUDGET -- a ratio of retries to successful requests -- so retries cannot amplify an outage.

THE SILENT FAILURE. When a dependency slows down, every caller retries, multiplying load on the thing already struggling. A service at 80 percent capacity is pushed past 300 by its own clients and cannot recover even after the original cause passes. No single caller looks wrong; each is politely retrying three times. Without jitter, every client retries at the same instant, arriving in waves.

The second silent failure is retrying a NON-IDEMPOTENT operation. The first attempt actually succeeded but its response was lost, so the retry charges the card twice. Nothing errors; the customer is billed twice and the logs show one success.

THE BUDGET IS THE PRODUCT. Retries are capped as a fraction of real traffic, so no number of callers can amplify a failure. Simple exponential backoff does not do this.

It REFUSES to retry what is not safe to retry: the caller declares idempotency, and a non-idempotent operation without an idempotency key is not retried. Defaulting to retry is the double-charge bug. Terminal errors are never retried -- a 400 will be a 400 forever and retrying it only burns budget. A server-supplied Retry-After beats any local guess. Every refusal names its reason. Fully deterministic: the caller injects the clock and the jitter source, so tests are exact rather than flaky.

VERIFIED: 77 tests. Every mutation was observed FAILING before the source was restored -- a test never seen to fail is a decoration. Independently reviewed by a verifier whose job was to find what is wrong, not to agree.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function classifyError(error: ClassifiableError): ErrorClass;
  export function decideRetry(input: RetryDecisionInput): RetryDecision;
  export function computeBackoffDelayMs( attempt: number, config: BackoffConfig, random: RandomFn ): number;

  export type JitterStrategy = "full" | "equal" | "none";
  export type ClockFn = () => number;
  export type RandomFn = () => number;
  export type ErrorClass = "retryable" | "terminal" | "unknown";