fix(clerk-js): Do not treat 429 responses as authentication failures

.changeset/fix-429-unauthenticated.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/shared': patch
+---
+
+Narrow the error conditions that trigger the unauthenticated flow (sign-out) to only high-confidence authentication failures (401, 422). Previously, all 4xx errors — including 429 rate limits — were treated as auth failures, which could sign users out during transient rate limiting. Non-auth errors from `setActive` now propagate to the caller instead of being silently swallowed.

integration/tests/resiliency.test.ts

@@ -4,6 +4,21 @@ import { appConfigs } from '../presets';
 import type { FakeUser } from '../testUtils';
 import { createTestUtils, testAgainstRunningApps } from '../testUtils';
 
+const make429ClerkResponse = () => ({
+  status: 429,
+  headers: { 'retry-after': '1' },
+  body: JSON.stringify({
+    errors: [
+      {
+        message: 'Too many requests',
+        long_message: 'Too many requests. Please retry later.',
+        code: 'rate_limit_exceeded',
+      },
+    ],
+    clerk_trace_id: 'some-trace-id',
+  }),
+});
+
 const make500ClerkResponse = () => ({
   status: 500,
   body: JSON.stringify({
@@ -296,6 +311,73 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withEmailCodes] })('resilienc
     });
   });
 
+  test.describe('429 rate limit resiliency', () => {
+    test('setActive surfaces 429 error to the developer instead of silently swallowing', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+
+      await u.po.signIn.goTo();
+      await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+      await u.po.expect.toBeSignedIn();
+
+      // Intercept touch requests to return 429
+      await page.route('**/v1/client/sessions/*/touch**', route => {
+        return route.fulfill(make429ClerkResponse());
+      });
+
+      // setActive should surface the 429 error so the developer can handle it
+      const error = await page.evaluate(async () => {
+        const session = window.Clerk?.session;
+        if (!session) {
+          return null;
+        }
+        try {
+          await window.Clerk?.setActive({ session });
+          return null;
+        } catch (e: any) {
+          return { status: e.status, message: e.message };
+        }
+      });
+
+      expect(error).not.toBeNull();
+      expect(error!.status).toBe(429);
+
+      await page.unrouteAll();
+
+      // The user must still be signed in — 429 should not trigger handleUnauthenticated
+      await u.po.expect.toBeSignedIn();
+    });
+
+    test('429 on /tokens does not cause recursive handleUnauthenticated calls', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+
+      await u.po.signIn.goTo();
+      await u.po.signIn.signInWithEmailAndInstantPassword({ email: fakeUser.email, password: fakeUser.password });
+      await u.po.expect.toBeSignedIn();
+
+      let clientRequestCount = 0;
+      await page.route('**/v1/client?**', route => {
+        clientRequestCount++;
+        return route.continue();
+      });
+
+      // Intercept token requests to return 429
+      await page.route('**/v1/client/sessions/*/tokens**', route => {
+        return route.fulfill(make429ClerkResponse());
+      });
+
+      // Clear the token cache so the next poller tick makes a fresh network request
+      await page.evaluate(() => window.Clerk?.session?.clearCache());
+
+      await page.waitForTimeout(3_000);
+
+      await page.unrouteAll();
+
+      // Without the fix, 429 on /tokens would trigger handleUnauthenticated → Client.fetch loop.
+      // With the fix, /v1/client should only see normal poller activity (not hundreds of requests).
+      expect(clientRequestCount).toBeLessThan(5);
+    });
+  });
+
   test.describe('clerk-js script loading', () => {
     test('recovers from transient network failure on clerk-js script load', async ({ page, context }) => {
       const u = createTestUtils({ app, page, context });

packages/clerk-js/src/core/auth/AuthCookieService.ts

@@ -3,7 +3,12 @@ import type { createClerkEventBus } from '@clerk/shared/clerkEventBus';
 import { clerkEvents } from '@clerk/shared/clerkEventBus';
 import type { createCookieHandler } from '@clerk/shared/cookie';
 import { setDevBrowserInURL } from '@clerk/shared/devBrowser';
-import { is4xxError, isClerkAPIResponseError, isClerkRuntimeError, isNetworkError } from '@clerk/shared/error';
+import {
+  isClerkAPIResponseError,
+  isClerkRuntimeError,
+  isNetworkError,
+  isUnauthenticatedError,
+} from '@clerk/shared/error';
 import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
 
@@ -215,8 +220,7 @@ export class AuthCookieService {
       return;
     }
 
-    //sign user out if a 4XX error
-    if (is4xxError(e)) {
+    if (isUnauthenticatedError(e)) {
       void this.clerk.handleUnauthenticated().catch(noop);
       return;
     }

packages/clerk-js/src/core/clerk.ts

@@ -8,6 +8,7 @@ import {
   is4xxError,
   isClerkAPIResponseError,
   isClerkRuntimeError,
+  isUnauthenticatedError,
 } from '@clerk/shared/error';
 import {
   disabledAllAPIKeysFeatures,
@@ -1595,7 +1596,7 @@ export class Clerk implements ClerkInterface {
               this.updateClient(updatedClient, { __internal_dangerouslySkipEmit: true });
             }
           } catch (e) {
-            if (is4xxError(e)) {
+            if (isUnauthenticatedError(e)) {
               void this.handleUnauthenticated();
             } else {
               throw e;
@@ -3174,8 +3175,10 @@ export class Clerk implements ClerkInterface {
     }
 
     await session.touch().catch(e => {
-      if (is4xxError(e)) {
+      if (isUnauthenticatedError(e)) {
         void this.handleUnauthenticated();
+      } else {
+        throw e;
       }
     });
   };

packages/clerk-js/src/core/resources/Session.ts

@@ -1,6 +1,12 @@
 import { createCheckAuthorization } from '@clerk/shared/authorization';
 import { isValidBrowserOnline } from '@clerk/shared/browser';
-import { ClerkOfflineError, ClerkWebAuthnError, is4xxError, MissingExpiredTokenError } from '@clerk/shared/error';
+import {
+  ClerkOfflineError,
+  ClerkWebAuthnError,
+  is4xxError,
+  is429Error,
+  MissingExpiredTokenError,
+} from '@clerk/shared/error';
 import {
   convertJSONToPublicKeyRequestOptions,
   serializePublicKeyCredentialAssertion,
@@ -146,17 +152,18 @@ export class Session extends BaseResource implements SessionResource {
   };
 
   getToken: GetToken = async (options?: GetTokenOptions): Promise<string | null> => {
-    // This will retry the getToken call if it fails with a non-4xx error
-    // For offline state, we use shorter retries (~15s total) before throwing ClerkOfflineError
-    // For other errors, we retry up to 8 times over ~3 minutes
+    // Retry on transient failures (5xx, network errors, 429 rate limits).
+    // Do not retry on deterministic client errors (4xx) — they won't resolve on their own.
+    // For offline state, we use shorter retries (~15s total) before throwing ClerkOfflineError.
+    // For other errors, we retry up to 8 times over ~3 minutes.
     try {
       const result = await retry(() => this._getToken(options), {
         factor: 1.55,
         initialDelay: 3 * 1000,
         maxDelayBetweenRetries: 50 * 1_000,
         jitter: false,
         shouldRetry: (error, iterationsCount) => {
-          if (is4xxError(error)) {
+          if (is4xxError(error) && !is429Error(error)) {
             return false;
           }
 

packages/shared/src/__tests__/error.spec.ts

@@ -1,7 +1,15 @@
 import { describe, expect, it } from 'vitest';
 
 import type { ErrorThrowerOptions } from '../error';
-import { buildErrorThrower, ClerkOfflineError, ClerkRuntimeError, isClerkRuntimeError } from '../error';
+import {
+  buildErrorThrower,
+  ClerkOfflineError,
+  ClerkRuntimeError,
+  is4xxError,
+  is429Error,
+  isClerkRuntimeError,
+  isUnauthenticatedError,
+} from '../error';
 
 describe('ErrorThrower', () => {
   const errorThrower = buildErrorThrower({ packageName: '@clerk/test-package' });
@@ -63,6 +71,58 @@ describe('ClerkRuntimeError', () => {
   });
 });
 
+describe('is4xxError', () => {
+  it('returns true for 4xx status codes', () => {
+    expect(is4xxError({ status: 400 })).toBe(true);
+    expect(is4xxError({ status: 401 })).toBe(true);
+    expect(is4xxError({ status: 429 })).toBe(true);
+    expect(is4xxError({ status: 499 })).toBe(true);
+  });
+
+  it('returns false for non-4xx status codes', () => {
+    expect(is4xxError({ status: 200 })).toBe(false);
+    expect(is4xxError({ status: 500 })).toBe(false);
+    expect(is4xxError({})).toBe(false);
+    expect(is4xxError(null)).toBe(false);
+  });
+});
+
+describe('is429Error', () => {
+  it('returns true for 429 status', () => {
+    expect(is429Error({ status: 429 })).toBe(true);
+  });
+
+  it('returns false for other status codes', () => {
+    expect(is429Error({ status: 400 })).toBe(false);
+    expect(is429Error({ status: 401 })).toBe(false);
+    expect(is429Error({ status: 500 })).toBe(false);
+    expect(is429Error({})).toBe(false);
+    expect(is429Error(null)).toBe(false);
+    expect(is429Error(undefined)).toBe(false);
+  });
+});
+
+describe('isUnauthenticatedError', () => {
+  it('returns true for authentication failure status codes', () => {
+    expect(isUnauthenticatedError({ status: 401 })).toBe(true);
+    expect(isUnauthenticatedError({ status: 422 })).toBe(true);
+  });
+
+  it('returns false for other 4xx status codes', () => {
+    expect(isUnauthenticatedError({ status: 400 })).toBe(false);
+    expect(isUnauthenticatedError({ status: 403 })).toBe(false);
+    expect(isUnauthenticatedError({ status: 404 })).toBe(false);
+    expect(isUnauthenticatedError({ status: 429 })).toBe(false);
+  });
+
+  it('returns false for non-4xx errors', () => {
+    expect(isUnauthenticatedError({ status: 200 })).toBe(false);
+    expect(isUnauthenticatedError({ status: 500 })).toBe(false);
+    expect(isUnauthenticatedError({})).toBe(false);
+    expect(isUnauthenticatedError(null)).toBe(false);
+  });
+});
+
 describe('ClerkOfflineError', () => {
   it('is an instance of ClerkRuntimeError', () => {
     const error = new ClerkOfflineError('Network request failed');

packages/shared/src/error.ts

@@ -17,6 +17,7 @@ export { ClerkRuntimeError, isClerkRuntimeError } from './errors/clerkRuntimeErr
 export { ClerkWebAuthnError } from './errors/webAuthNError';
 
 export {
+  is429Error,
   is4xxError,
   isCaptchaError,
   isEmailLinkError,
@@ -26,6 +27,7 @@ export {
   isPasswordPwnedError,
   isPasswordCompromisedError,
   isReverificationCancelledError,
+  isUnauthenticatedError,
   isUnauthorizedError,
   isUserLockedError,
 } from './errors/helpers';

packages/shared/src/errors/helpers.ts

@@ -37,6 +37,36 @@ export function is4xxError(e: any): boolean {
   return !!status && status >= 400 && status < 500;
 }
 
+/**
+ * Checks if the provided error is a 429 (Too Many Requests) error.
+ *
+ * @internal
+ */
+export function is429Error(e: any): boolean {
+  return e?.status === 429;
+}
+
+/**
+ * Checks if the provided error indicates the user's session is no longer valid
+ * and should trigger the unauthenticated flow (e.g. sign-out / redirect to sign-in).
+ *
+ * Only matches explicit authentication failure status codes:
+ * - 401: session is invalid or expired
+ * - 422: invalid session state (e.g. missing_expired_token)
+ *
+ * 404 is intentionally excluded despite being returned for "session not found",
+ * because it's also returned for unrelated resources (org not found, JWT template
+ * not found) and shares the same `resource_not_found` error code, making it
+ * impossible to distinguish. Session-not-found 401s are already handled directly
+ * by Base._fetch.
+ *
+ * @internal
+ */
+export function isUnauthenticatedError(e: any): boolean {
+  const status = e?.status;
+  return status === 401 || status === 422;
+}
+
 /**
  * Checks if the provided error is a network error.
  *