Retries

const llm = new VernLLM({
  client: openai,
  model: 'gpt-4o',
  maxRetries: 3, // retries after the first attempt, so 4 attempts total
  baseDelayMs: 500, // base for exponential backoff between retries
});

Every call() retries transient failures automatically. maxRetries defaults to 1 (2 attempts total), so this is active even if you never touch the option.

Backoff and jitter

Each retry waits longer than the last, and the exact wait is randomized within a range rather than fixed:

exp = min(baseDelayMs * 2 ** attempt, maxDelayMs);
delay = exp / 2 + random() * (exp / 2);

This is full jitter: the delay lands somewhere between half and all of the computed exponential value, instead of every caller waiting the identical amount. When many callers hit a failure at the same time, full jitter spreads their retries out instead of having them all retry in lockstep and hit the provider again at the same instant.

The delay is capped at DEFAULT_MAX_DELAY_MS (10 seconds) regardless of attempt, so a high maxRetries never produces an unbounded wait.

Honoring Retry-After

If the failed attempt's error carries a Retry-After header, that value is used for the wait instead of the computed backoff:

recoverDelay = retryAfterMs ?? getBackoffDelay(baseDelayMs, attempt);

What gets retried

shouldRetry skips a retry when any of these are true:

• The signal has already aborted
• error.type is parse or validation, since these are deterministic response processing failures that a retry will not fix
• error.status is in nonRetryableStatus (default 400, 401, 403, 404, 422)

Everything else, including timeouts, 5xx errors, network failures, and unknown errors, is retried up to maxRetries.

Cancelling mid retry

If a signal fires while a retry is waiting out its backoff delay, the pending wait is cancelled immediately rather than sitting idle until the delay finishes. An abort during backoff is never retried, it is treated as a deliberate cancellation. See Cancellation & Timeouts for the full abort lifecycle.

Reading attempt history

Every normalized LLMError carries an optional attempts array. Each entry has the attempt's index and a snapshot of that attempt's error: an LLMErrorSnapshot with message, type, code, status, issues, retryAfterMs, retryable, and its own nested attempts if that attempt was itself the terminal failure of a retry loop. It's a snapshot, not a live LLMError, since a past attempt is a record, not something you'd catch or rethrow. cause isn't part of it. cause is meant to be read on the live error you actually caught (err.cause), not carried inside recorded history. Each entry can also carry request, an LLMRequestSnapshot of what was actually sent for that attempt, with auth headers always removed. See Error Handling for cause and for the full LLMRequestSnapshot shape.

try {
  await llm.call({ userContent: 'hello' });
} catch (err) {
  if (isLLMError(err)) {
    for (const attempt of err.attempts ?? []) {
      console.log(attempt.index, attempt.error.type);
    }
  }
}

attempts is absent when nothing was retried, for example a call that failed on its first and only try. With fallback configured, each FallbackAttempt on a FallbackExhaustedError extends this same shape, adding provider and model, and that attempt's own error.attempts still holds the retries made against that one target. See Provider Fallback for FallbackExhaustedError itself.

Options reference

See Configuration for every option alongside timeout and circuit breaker settings.