Retries that know when to stop.

• You declare whether it is safe

  retry() throws unless you pass idempotency. A non-idempotent operation is never retried, even on a network error, because the server may already have done the work.

• Four limits, enforced together

  Attempts, a total deadline, a shared budget and cancellation all apply. The first to say no ends the loop and names itself in RetryError.reason.

• A budget shared across calls

  maxAttempts bounds one call. A RetryBudget bounds all of them, so an outage cannot multiply your traffic by the attempt limit.

• Retry-After, within reason

  A server delay is a floor on the wait. If it asks for more than maxServerDelayMs, the retry is abandoned instead of silently shortened.

• Events without secrets

  No bodies or headers. The fetch wrapper strips query strings, fragments and URL credentials, and swallows errors thrown by your onEvent handler.

• Works with the fetch you have

  Wrap globalThis.fetch, undici, an instrumented fetch or a test double. Zero dependencies, ESM, and no Node imports outside retrypilot/node.

Read what it cannot do →

1. 1

   Wrap an operation

   Forward the attempt's signal so abandoned work is actually cancelled.

   ts

   import { RetryBudget, createRetryPolicy, retry } from "retrypilot";
   
   declare const db: { fetchUser(id: string, options: { signal: AbortSignal }): Promise<{ name: string }> };
   declare const cache: { get(key: string): Promise<string> };
   
   // One call. Declaring idempotency is required: there is no default.
   const user = await retry(({ signal }) => db.fetchUser("42", { signal }), {
     idempotency: "idempotent",
     maxAttempts: 4,
     totalTimeoutMs: 10_000, // the whole call, waits included
     attemptTimeoutMs: 2_000, // each attempt
   });
   
   // Many calls, one policy, one shared budget.
   const budget = new RetryBudget({ capacity: 20, successRefund: 0.1 });
   const policy = createRetryPolicy({ idempotency: "idempotent", maxAttempts: 3, budget });
   
   await policy.execute(() => cache.get("a"));
   await policy.execute(() => cache.get("b"), { maxAttempts: 5 });
   
   export { user };

2. 2

   Wrap the fetch you use

   GET is retried, POST is sent once unless you opt in, and stream bodies are never replayed.

   ts

   import { createRetryFetch } from "retrypilot/http";
   
   const fetchWithRetry = createRetryFetch(fetch, {
     maxAttempts: 4,
     totalTimeoutMs: 15_000,
     attemptTimeoutMs: 5_000,
   });
   
   // GET is idempotent: retried on 503, 429 and network errors.
   await fetchWithRetry("https://api.example.com/items");
   
   // POST is not: sent once, unless you opt in per request or by header.
   await fetchWithRetry("https://api.example.com/items", { method: "POST", body: "{}" });
   await fetchWithRetry("https://api.example.com/items", { method: "POST", body: "{}", retry: { idempotent: true } });

3. 3

   Share a budget, watch the events

   One bucket for every call, and a typed event for every decision.

   ts

   import { RetryBudget } from "retrypilot";
   
   // Each retry spends 1 token, each success earns 0.1 back. When the bucket is empty,
   // retries stop for every call that shares it: an outage cannot triple your traffic.
   export const budget = new RetryBudget({ capacity: 20, retryCost: 1, successRefund: 0.1 });

   ts

   import { RetryError, retry } from "retrypilot";
   
   declare const op: () => Promise<string>;
   declare const log: { warn(entry: object): void };
   
   try {
     await retry(op, {
       idempotency: "idempotent",
       name: "load-profile",
       onEvent(e) {
         if (e.type === "attempt-failed") log.warn({ attempt: e.attempt, ms: e.durationMs });
         if (e.type === "retry-scheduled") log.warn({ waitMs: e.delayMs });
         if (e.type === "retry-abandoned") log.warn({ reason: e.reason });
       },
     });
   } catch (error) {
     if (error instanceof RetryError) {
       // 'non-retryable' | 'not-idempotent' | 'max-attempts' | 'deadline-exceeded'
       // | 'budget-exhausted' | 'server-delay-too-long' | 'aborted'
       log.warn({ reason: error.reason, attempts: error.attempts, elapsedMs: error.elapsedMs });
     }
   }

• idempotencyRequired. idempotent or non-idempotent. The library never guesses.
• maxAttemptsAttempts including the first. Default 3.
• totalTimeoutMsWall-clock limit for the whole call, waits included.
• attemptTimeoutMsLimit for each attempt, clipped to the time remaining.
• budgetA RetryBudget shared by every call that should draw on the same retries.
• isRetryableReplace the default classifier. It can also return a server-directed delay.

See every option →