Function apiRetryDecision

src/lib/http.ts:726–779

(
  code: ErrorCode,
  attempt: number,
  retryAfterSec: number | undefined,
  random: () => number,
  retryOnConflict = true,
  retryOnRateLimit = true,
)

}

function apiRetryDecision(
  code: ErrorCode,
  attempt: number,
  retryAfterSec: number | undefined,
  random: () => number,
  retryOnConflict = true,
  retryOnRateLimit = true,
): RetryDecision {
  switch (code) {
    // M3.2 piece-1 / piece-2: `PRECONDITION_FAILED` (etag mismatch),
    // `IDEMPOTENCY_BODY_MISMATCH` (caller mutated body across retries),
    // and `PAYLOAD_TOO_LARGE` (350 KB cap) are all caller-side bugs —
    // never retry, exit immediately with the typed envelope.
    // INSUFFICIENT_CREDITS is non-retriable: out-of-credits cannot self-heal.
    // The RATE_LIMITED credits sub-case is re-mapped to INSUFFICIENT_CREDITS
    // in parseEnvelopeBody (errors.ts) before apiRetryDecision is called,
    // so the genuine per-minute throttle (RATE_LIMITED) reaches the RATE_LIMITED
    // case below and retries normally.
    // FEATURE_GATED is non-retriable: a paid-feature gate can't self-heal with
    // retries — the caller must upgrade their plan first.
    case 'AUTH_REQUIRED':
    case 'AUTH_INVALID':
    case 'AUTH_FORBIDDEN':
    case 'NOT_FOUND':
    case 'VALIDATION_ERROR':
    case 'PAYLOAD_TOO_LARGE':
    case 'PRECONDITION_FAILED':
    case 'IDEMPOTENCY_BODY_MISMATCH':
    case 'UNSUPPORTED':
    case 'INSUFFICIENT_CREDITS':
    case 'FEATURE_GATED':
      return { retry: false, delayMs: 0 };
    case 'CONFLICT':
      // Read paths (e.g. GET /failure) retry once: 409 = mid-mutation snapshot.
      // Write paths (e.g. POST /runs) must NOT retry: 409 = another run is in
      // flight (persistent), retrying would enqueue a second run.
      if (!retryOnConflict) return { retry: false, delayMs: 0 };
      if (attempt >= MAX_ATTEMPTS_CONFLICT) return { retry: false, delayMs: 0 };
      return { retry: true, delayMs: CONFLICT_DELAY_MS };
    case 'INTERNAL':
      if (attempt >= MAX_ATTEMPTS_INTERNAL) return { retry: false, delayMs: 0 };
      return { retry: true, delayMs: INTERNAL_DELAY_MS };
    case 'RATE_LIMITED':
      if (!retryOnRateLimit) return { retry: false, delayMs: 0 };
      if (attempt >= MAX_ATTEMPTS_RATE_LIMITED) return { retry: false, delayMs: 0 };
      return {
        retry: true,
        delayMs: Math.min(Math.max(0, (retryAfterSec ?? 1) * 1000), MAX_RATE_LIMITED_DELAY_MS),
      };
    case 'UNAVAILABLE':
      if (attempt >= MAX_ATTEMPTS_UNAVAILABLE) return { retry: false, delayMs: 0 };
      return { retry: true, delayMs: backoffDelay(attempt, random) };
  }
}

function backoffDelay(attempt: number, random: () => number): number {
  const base = RETRY_BASE_MS * Math.pow(2, attempt - 1);