refactor: Replace is4xxError+is429Error with isUnauthenticatedError helper

Introduce isUnauthenticatedError that encapsulates the "4xx but not 429"
logic in one place, making the intent self-documenting and preventing
future callers from accidentally treating rate limits as auth failures.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: brkalow

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

@@ -4,11 +4,10 @@ import { clerkEvents } from '@clerk/shared/clerkEventBus';
 import type { createCookieHandler } from '@clerk/shared/cookie';
 import { setDevBrowserInURL } from '@clerk/shared/devBrowser';
 import {
-  is429Error,
-  is4xxError,
   isClerkAPIResponseError,
   isClerkRuntimeError,
   isNetworkError,
+  isUnauthenticatedError,
 } from '@clerk/shared/error';
 import type { Clerk, InstanceType } from '@clerk/shared/types';
 import { noop } from '@clerk/shared/utils';
@@ -221,9 +220,7 @@ export class AuthCookieService {
       return;
     }
 
-    // 429 (rate limited) is not an auth failure — the session may still be valid.
-    // Treat it the same as a transient error and degrade gracefully.
-    if (is4xxError(e) && !is429Error(e)) {
+    if (isUnauthenticatedError(e)) {
       void this.clerk.handleUnauthenticated().catch(noop);
       return;
     }

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

@@ -5,10 +5,10 @@ import {
   ClerkRuntimeError,
   EmailLinkError,
   EmailLinkErrorCodeStatus,
-  is429Error,
   is4xxError,
   isClerkAPIResponseError,
   isClerkRuntimeError,
+  isUnauthenticatedError,
 } from '@clerk/shared/error';
 import {
   disabledAllAPIKeysFeatures,
@@ -1596,9 +1596,11 @@ export class Clerk implements ClerkInterface {
               this.updateClient(updatedClient, { __internal_dangerouslySkipEmit: true });
             }
           } catch (e) {
-            if (is4xxError(e) && !is429Error(e)) {
+            if (isUnauthenticatedError(e)) {
               void this.handleUnauthenticated();
-            } else if (!is429Error(e)) {
+            } else if (!is4xxError(e)) {
+              // Swallow 4xx errors like 429 (rate limit) that are not auth failures.
+              // Non-4xx errors (5xx, network) should still propagate.
               throw e;
             }
           }
@@ -3175,7 +3177,7 @@ export class Clerk implements ClerkInterface {
     }
 
     await session.touch().catch(e => {
-      if (is4xxError(e) && !is429Error(e)) {
+      if (isUnauthenticatedError(e)) {
         void this.handleUnauthenticated();
       }
     });

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

@@ -3,8 +3,7 @@ import { isValidBrowserOnline } from '@clerk/shared/browser';
 import {
   ClerkOfflineError,
   ClerkWebAuthnError,
-  is429Error,
-  is4xxError,
+  isUnauthenticatedError,
   MissingExpiredTokenError,
 } from '@clerk/shared/error';
 import {
@@ -162,8 +161,7 @@ export class Session extends BaseResource implements SessionResource {
         maxDelayBetweenRetries: 50 * 1_000,
         jitter: false,
         shouldRetry: (error, iterationsCount) => {
-          // 429 is a rate limit, not an auth error — retry with backoff
-          if (is4xxError(error) && !is429Error(error)) {
+          if (isUnauthenticatedError(error)) {
             return false;
           }
 

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

@@ -8,6 +8,7 @@ import {
   is429Error,
   is4xxError,
   isClerkRuntimeError,
+  isUnauthenticatedError,
 } from '../error';
 
 describe('ErrorThrower', () => {
@@ -101,6 +102,27 @@ describe('is429Error', () => {
   });
 });
 
+describe('isUnauthenticatedError', () => {
+  it('returns true for auth-related 4xx errors', () => {
+    expect(isUnauthenticatedError({ status: 400 })).toBe(true);
+    expect(isUnauthenticatedError({ status: 401 })).toBe(true);
+    expect(isUnauthenticatedError({ status: 403 })).toBe(true);
+    expect(isUnauthenticatedError({ status: 404 })).toBe(true);
+    expect(isUnauthenticatedError({ status: 422 })).toBe(true);
+  });
+
+  it('returns false for 429 (rate limit)', () => {
+    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

@@ -27,6 +27,7 @@ export {
   isPasswordPwnedError,
   isPasswordCompromisedError,
   isReverificationCancelledError,
+  isUnauthenticatedError,
   isUnauthorizedError,
   isUserLockedError,
 } from './errors/helpers';

packages/shared/src/errors/helpers.ts

@@ -46,6 +46,22 @@ 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).
+ *
+ * This is a 4xx client error that is NOT a rate limit (429). Rate-limited requests
+ * are transient — the session may still be valid, so they should be retried rather
+ * than treated as authentication failures.
+ *
+ * Use this instead of `is4xxError` when deciding whether to call `handleUnauthenticated`.
+ *
+ * @internal
+ */
+export function isUnauthenticatedError(e: any): boolean {
+  return is4xxError(e) && !is429Error(e);
+}
+
 /**
  * Checks if the provided error is a network error.
  *