@@ -0,0 +1,124 @@
+import { interruptibleSleep } from '@sim/utils/helpers'
+import { backoffWithJitter } from '@sim/utils/retry'
+import { TokenServiceAccountValidationError } from '@/lib/credentials/token-service-accounts/errors'
+
+/**
+ * How a failed token request is retried:
+ * - `permanent`: the provider refused the credentials or the account (or the failure is not a
+ *   provider answer at all); asking again cannot help until the secret changes.
+ * - `throttled`: a 429, or an outage with a `Retry-After`; the provider said when to come back.
+ * - `transient`: any other outage (5xx, timeout, network failure, malformed token response).
+ */
+export type TokenRequestFailureKind = 'permanent' | 'throttled' | 'transient'
+
+export interface TokenRequestFailure {
+  kind: TokenRequestFailureKind
+  /** Non-permanent failures in a row, this one included; 1 for a permanent failure. */
+  consecutiveFailures: number
+  /** How long the failure is replayed before the provider is asked again. */
+  replayMs: number
+}
+
+/**
+ * A token with less than this left is treated as expired and never served, so clock skew and a
+ * call already in flight cannot carry it past its expiry.
+ */
+export const TOKEN_EXPIRY_MARGIN_MS = 30_000
+
+/**
+ * How long a remembered failure outlives its replay, so the next failure continues the streak
+ * and backs off longer. A failure after a quieter gap starts a new streak.
+ */
+export const TOKEN_FAILURE_STREAK_RETENTION_MS = 5 * 60_000
+
+/** A refusal of the credentials is replayed this long, so a revoked secret does not hammer the provider. */
+const PERMANENT_FAILURE_REPLAY_MS = 30_000
+/**
+ * A provider's `Retry-After` is honored for at most five minutes. Microsoft Entra ID, the most
+ * explicit documented case, throttles client-credentials token requests with `Retry-After: 60`;
+ * five minutes leaves room for per-minute provider windows while a proxy or a misbehaving provider
+ * answering with hours cannot lock every workflow on an application out for that long.
+ */
+const RETRY_AFTER_BOUNDS = { baseMs: 1_000, maxMs: 5 * 60_000 } as const
+/**
+ * An outage is retried after 5 s at first (Entra's resilience guidance: the first back-off retry at
+ * least 5 s after the response), doubling while it continues, up to 30 s: the flat replay every
+ * failure used to get, so no outage is replayed longer than before.
+ */
+const OUTAGE_BACKOFF = { baseMs: 5_000, maxMs: 30_000 } as const
+/** The pause before the one in-request retry: MSAL's documented one-second retry-once. */
+const IN_REQUEST_RETRY_DELAY = { baseMs: 1_000, maxMs: 1_000 } as const
+/**
+ * A failed attempt is retried only when it failed this quickly. A timed-out attempt (10 s) is
+ * never retried in-request, and a retried exchange holding a coordinated application lock stays
+ * within the 15 s its waiters allow: 2 s, the 1.2 s pause, and one more 10 s attempt.
+ */
+const IN_REQUEST_RETRY_BUDGET_MS = 2_000
+
+/** Classifies a failed token request; see {@link TokenRequestFailureKind}. */
+export function classifyTokenRequestFailure(error: unknown): TokenRequestFailureKind {
+  if (!(error instanceof TokenServiceAccountValidationError)) return 'permanent'
+  if (error.code !== 'provider_unavailable') return 'permanent'
+  return error.status === 429 || error.retryAfterMs !== undefined ? 'throttled' : 'transient'
+}
+
+/**
+ * Decides how long a failed token request is replayed. A failure carrying `retryAfterMs` (the
+ * provider's `Retry-After`, or what remains of a replay another layer already decided) is replayed
+ * that long within 1 s to 5 min. Otherwise a permanent failure is replayed 30 s and an outage backs
+ * off from 5 s to 30 s with jitter as it continues. `previousConsecutiveFailures` counts the
+ * non-permanent failures immediately before this one (0 after a success or a permanent failure).
+ */
+export function assessTokenRequestFailure(
+  error: unknown,
+  previousConsecutiveFailures = 0
+): TokenRequestFailure {
+  const kind = classifyTokenRequestFailure(error)
+  const consecutiveFailures = kind === 'permanent' ? 1 : previousConsecutiveFailures + 1
+  const retryAfterMs =
+    error instanceof TokenServiceAccountValidationError ? error.retryAfterMs : undefined
+  if (retryAfterMs !== undefined) {
+    return {
+      kind,
+      consecutiveFailures,
+      replayMs: backoffWithJitter(1, retryAfterMs, RETRY_AFTER_BOUNDS),
+    }
+  }
+  if (kind === 'permanent') {
+    return { kind, consecutiveFailures, replayMs: PERMANENT_FAILURE_REPLAY_MS }
+  }
+  return {
+    kind,
+    consecutiveFailures,
+    replayMs: Math.min(
+      backoffWithJitter(consecutiveFailures, null, OUTAGE_BACKOFF),
+      OUTAGE_BACKOFF.maxMs
+    ),
+  }
+}
+
+/**
+ * Runs a token request, retrying a transient failure once after about a second when the failed
+ * attempt was quick (see {@link IN_REQUEST_RETRY_BUDGET_MS}). Throttled and permanent failures,
+ * and an aborted `signal`, are never retried.
+ */
+export async function requestTokenWithRetry<T>(
+  request: () => Promise<T>,
+  signal?: AbortSignal
+): Promise<T> {
+  const startedAt = Date.now()
+  try {
+    return await request()
+  } catch (error) {
+    signal?.throwIfAborted()
+    if (
+      classifyTokenRequestFailure(error) !== 'transient' ||
+      Date.now() - startedAt > IN_REQUEST_RETRY_BUDGET_MS
+    ) {
+      throw error
+    }
+    await interruptibleSleep(backoffWithJitter(1, null, IN_REQUEST_RETRY_DELAY), signal)
+    signal?.throwIfAborted()
+    return request()
+  }
+}
@@ -2,12 +2,13 @@ import { credential } from '@sim/db/schema'
 import { createDeferred } from '@sim/testing/helpers/deferred'
 import { queueTableRows, resetDbChainMock } from '@sim/testing/mocks/database.mock'
 import { encryptionMock, encryptionMockFns } from '@sim/testing/mocks/encryption.mock'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import {
   CLIENT_CREDENTIAL_ACCOUNT_SECRET_TYPE,
   RAMP_SERVICE_ACCOUNT_PROVIDER_ID,
 } from '@/lib/credentials/client-credential-accounts/descriptors'
 import * as clientAccounts from '@/lib/credentials/client-credential-accounts/server'
+import { TokenServiceAccountValidationError } from '@/lib/credentials/token-service-accounts/errors'
 import {
   forgetRejectedClientCredentialToken,
   resolveServiceAccountToken,
@@ -152,3 +153,173 @@ describe('client credential token cache', () => {
     }
   })
 })
+
+describe('client credential token refresh after a failed mint', () => {
+  const refused = () =>
+    new TokenServiceAccountValidationError('invalid_credentials', 401, { step: 'mint' })
+  const unavailable = (status = 502, retryAfterMs?: number) =>
+    new TokenServiceAccountValidationError(
+      'provider_unavailable',
+      status,
+      { step: 'mint' },
+      {
+        retryAfterMs,
+      }
+    )
+
+  /** Resolves with fake timers running, so an in-mint retry pause elapses without real waiting. */
+  async function resolveFor(credentialId: string) {
+    queueTableRows(credential, [storedCredential])
+    const outcome = resolveServiceAccountToken(credentialId, RAMP_SERVICE_ACCOUNT_PROVIDER_ID).then(
+      (value) => ({ value }),
+      (error: unknown) => ({ error })
+    )
+    await vi.runAllTimersAsync()
+    return outcome
+  }
+
+  function minter() {
+    const mint = vi.fn<clientAccounts.ClientCredentialAccountMinter>()
+    vi.spyOn(clientAccounts, 'getClientCredentialAccountMinter').mockReturnValue(mint)
+    return mint
+  }
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('keeps serving a still-valid token while its early refresh fails transiently', async () => {
+    const mint = minter()
+    mint.mockResolvedValueOnce({ accessToken: 'current-token', expiresInSeconds: 600 })
+    await expect(resolveFor('ramp-refresh-outage')).resolves.toEqual({
+      value: { accessToken: 'current-token' },
+    })
+    mint.mockRejectedValue(unavailable())
+    vi.advanceTimersByTime(6 * 60_000)
+
+    await expect(resolveFor('ramp-refresh-outage')).resolves.toEqual({
+      value: { accessToken: 'current-token' },
+    })
+    const askedDuringRefresh = mint.mock.calls.length
+    await expect(resolveFor('ramp-refresh-outage')).resolves.toEqual({
+      value: { accessToken: 'current-token' },
+    })
+    expect(askedDuringRefresh).toBeGreaterThan(1)
+    expect(mint).toHaveBeenCalledTimes(askedDuringRefresh)
+  })
+
+  it('reports the failed refresh once the cached token has run out', async () => {
+    const mint = minter()
+    mint.mockResolvedValueOnce({ accessToken: 'current-token', expiresInSeconds: 600 })
+    await resolveFor('ramp-refresh-expired')
+    mint.mockRejectedValue(unavailable())
+    vi.advanceTimersByTime(600_000 - 20_000)
+
+    await expect(resolveFor('ramp-refresh-expired')).resolves.toEqual({
+      error: expect.objectContaining({ code: 'provider_unavailable' }),
+    })
+  })
+
+  it('stops serving the cached token once the provider refuses the credentials', async () => {
+    const mint = minter()
+    mint.mockResolvedValueOnce({ accessToken: 'current-token', expiresInSeconds: 600 })
+    await resolveFor('ramp-refresh-refused')
+    mint.mockRejectedValue(refused())
+    vi.advanceTimersByTime(6 * 60_000)
+
+    await expect(resolveFor('ramp-refresh-refused')).resolves.toEqual({
+      error: expect.objectContaining({ code: 'invalid_credentials' }),
+    })
+    expect(mint).toHaveBeenCalledTimes(2)
+  })
+
+  it('retries a quick transient failure once inside the mint', async () => {
+    const mint = minter()
+    mint.mockRejectedValueOnce(unavailable(503)).mockResolvedValueOnce(token)
+
+    await expect(resolveFor('ramp-retry-once')).resolves.toEqual({
+      value: { accessToken: token.accessToken },
+    })
+    expect(mint).toHaveBeenCalledTimes(2)
+  })
+
+  it('does not retry an attempt that took as long as a provider timeout', async () => {
+    const mint = minter()
+    mint.mockImplementation(async () => {
+      vi.setSystemTime(Date.now() + 10_000)
+      throw unavailable()
+    })
+
+    await expect(resolveFor('ramp-timed-out')).resolves.toEqual({
+      error: expect.objectContaining({ code: 'provider_unavailable' }),
+    })
+    expect(mint).toHaveBeenCalledOnce()
+  })
+
+  it('replays a refusal of the credentials for 30 seconds without retrying it', async () => {
+    const mint = minter()
+    mint.mockRejectedValue(refused())
+
+    await resolveFor('ramp-refused')
+    vi.advanceTimersByTime(29_000)
+    await expect(resolveFor('ramp-refused')).resolves.toEqual({
+      error: expect.objectContaining({ code: 'invalid_credentials' }),
+    })
+    expect(mint).toHaveBeenCalledOnce()
+
+    vi.advanceTimersByTime(2_000)
+    await resolveFor('ramp-refused')
+    expect(mint).toHaveBeenCalledTimes(2)
+  })
+
+  it.each([
+    ['as long as a throttled provider asks', 120_000, 120_000],
+    ['no longer than five minutes, whatever the provider asks', 3_600_000, 300_000],
+  ])('waits %s before asking again', async (_case, retryAfterMs, waitMs) => {
+    const mint = minter()
+    const credentialId = `ramp-throttled-${retryAfterMs}`
+    mint.mockRejectedValueOnce(unavailable(429, retryAfterMs)).mockResolvedValueOnce(token)
+
+    await expect(resolveFor(credentialId)).resolves.toEqual({
+      error: expect.objectContaining({ code: 'provider_unavailable', status: 429 }),
+    })
+    vi.advanceTimersByTime(waitMs - 1_000)
+    await expect(resolveFor(credentialId)).resolves.toEqual({
+      error: expect.objectContaining({ status: 429 }),
+    })
+    expect(mint).toHaveBeenCalledOnce()
+
+    vi.advanceTimersByTime(2_000)
+    await expect(resolveFor(credentialId)).resolves.toEqual({
+      value: { accessToken: token.accessToken },
+    })
+  })
+
+  it('backs off an outage briefly at first, longer while it lasts, and never past 30 seconds', async () => {
+    const mint = minter()
+    mint.mockRejectedValue(unavailable())
+
+    await resolveFor('ramp-outage')
+    const firstAttempt = mint.mock.calls.length
+    vi.advanceTimersByTime(6_001)
+    await resolveFor('ramp-outage')
+    const secondAttempt = mint.mock.calls.length
+    expect(secondAttempt).toBeGreaterThan(firstAttempt)
+
+    vi.advanceTimersByTime(6_001)
+    await resolveFor('ramp-outage')
+    expect(mint).toHaveBeenCalledTimes(secondAttempt)
+
+    for (let attempt = 0; attempt < 6; attempt++) {
+      const asked = mint.mock.calls.length
+      vi.advanceTimersByTime(30_001)
+      await resolveFor('ramp-outage')
+      expect(mint.mock.calls.length).toBeGreaterThan(asked)
+    }
+  })
+})