fix(clerk-js): Do not treat 429 responses as authentication failures by brkalow · Pull Request #8004 · clerk/javascript

brkalow · 2026-03-06T15:59:24Z

Summary

429 (Too Many Requests) responses were being caught by is4xxError and triggering handleUnauthenticated, which signs the user out. This caused a cascading failure pattern observed in production telemetry for a customer.

Token fetch fails with a legitimate 4xx (e.g. authentication_invalid)
handleUnauthenticated fires and calls /touch to recover
/touch returns 429 (rate limited)
429 triggers handleUnauthenticated again (treated as auth failure)
Each retry hits 429 → infinite loop (30+ retries in 11 seconds observed)
User gets forcibly redirected to sign-in

Changes

@clerk/shared: Add is429Error helper alongside existing is4xxError
AuthCookieService.handleGetTokenError: Exclude 429 from triggering handleUnauthenticated — fall through to degraded status instead
Clerk.setActive: Exclude 429 from triggering handleUnauthenticated, and also don't re-throw (swallow like other transient errors)
Clerk.#touchCurrentSession: Exclude 429 from triggering handleUnauthenticated
Session.getToken retry logic: Allow 429 to be retried with exponential backoff instead of immediately giving up (was blocked by is4xxError in shouldRetry)

Telemetry evidence (7-day window)

Event	Count
`handleUnauthenticated triggered`	650 (285 unique sessions)
`/touch` returning 429	Majority of `request failed` errors during cascades
Top offending session	59 `handleUnauthenticated` events from a single session

Test plan

is429Error unit tests pass (true for 429, false for all other statuses including null/undefined)
is4xxError unit tests pass (still returns true for 429 — no breaking change)
All 59 Session tests pass
All 488 clerk-js core tests pass (36 test files)
Verify in staging that 429 from /touch no longer triggers sign-out
Monitor telemetry for reduction in handleUnauthenticated triggered events

🤖 Generated with Claude Code

Summary by CodeRabbit

Bug Fixes
- Fixed handling of rate-limit (HTTP 429) responses so they no longer trigger sign-out; clients now enter a degraded state and retry, preserving signed-in sessions and avoiding recursive unauthenticated loops.
Tests
- Added resiliency tests covering 429 rate-limit scenarios and unauthenticated-edge cases to ensure stable runtime behavior under high traffic.

429 (Too Many Requests) responses were being caught by `is4xxError` and triggering `handleUnauthenticated`, which signs the user out. This caused a cascading failure: the unauthenticated flow calls `/touch`, which returns 429 due to rate limiting, which triggers `handleUnauthenticated` again — creating an infinite retry loop that forces users to re-authenticate even though their session is still valid. Changes: - Add `is429Error` helper to `@clerk/shared` - Exclude 429 from triggering `handleUnauthenticated` in `AuthCookieService.handleGetTokenError`, `Clerk.setActive`, and `Clerk.#touchCurrentSession` - Allow 429 to be retried in `Session.getToken` instead of immediately failing (was blocked by `is4xxError` check in `shouldRetry`) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vercel · 2026-03-06T15:59:30Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 6, 2026 9:03pm

changeset-bot · 2026-03-06T15:59:36Z

🦋 Changeset detected

Latest commit: f11e4d4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 21 packages

Name	Type
@clerk/clerk-js	Patch
@clerk/shared	Patch
@clerk/chrome-extension	Patch
@clerk/expo	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/expo-passkeys	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2026-03-06T16:02:50Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@8004

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8004

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8004

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8004

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8004

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8004

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8004

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8004

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8004

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8004

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8004

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8004

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8004

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8004

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8004

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8004

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8004

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8004

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8004

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8004

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8004

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8004

commit: f11e4d4

…elper 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>

coderabbitai · 2026-03-06T16:04:51Z

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds two predicates, is429Error and isUnauthenticatedError, to shared error helpers and re-exports them. Call sites in AuthCookieService, clerk.ts, and Session.ts now use isUnauthenticatedError instead of a generic 4xx check so HTTP 429 responses are treated as rate-limited (degraded/retryable). A changeset documenting the fix was added. Integration tests were added for 429 resiliency and related unauthenticated scenarios.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: preventing 429 rate-limit responses from being treated as authentication failures, which is the core fix across all modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/clerk-js/src/core/clerk.ts`:
- Around line 1599-1602: setActive can still fail when newSession?.getToken()
throws a 429 because the current catch rethrows 429; change the getToken catch
so 429 is not rethrown — treat 429 like the throttling case and swallow it (or
route to the same non-throw handling) instead of throwing. Concretely, update
the catch around newSession?.getToken() in setActive/__internal_touch so that
you only rethrow for errors that are neither 4xx nor is429Error(e) (use
is4xxError(e) and is429Error(e) checks) and call this.handleUnauthenticated()
for 4xx errors as before; ensure is429Error(e) branch does not rethrow.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: ac8cf484-1b7b-4811-9fc5-d1ebe64b67f2

📥 Commits

Reviewing files that changed from the base of the PR and between 79d0ecf and 3a4ea45.

📒 Files selected for processing (7)

.changeset/fix-429-unauthenticated.md
packages/clerk-js/src/core/auth/AuthCookieService.ts
packages/clerk-js/src/core/clerk.ts
packages/clerk-js/src/core/resources/Session.ts
packages/shared/src/__tests__/error.spec.ts
packages/shared/src/error.ts
packages/shared/src/errors/helpers.ts

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

…tests - Let 429 errors from touch propagate to the caller in setActive instead of silently swallowing, so developers can handle rate limits (e.g. show retry UI using error.retryAfter) - Add integration tests for 429 resiliency: user stays signed in, status goes to degraded (not error), and no recursive handleUnauthenticated loop Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The "status transitions to degraded" test was unreliable because 429 on /tokens triggers retry logic (up to 8 retries) before surfacing the error to handleGetTokenError. The remaining 3 tests cover the critical app-level behavior. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…th failures Only 401 (invalid/expired session) and 422 (invalid session state) should trigger the unauthenticated flow. Other 4xx codes are excluded: - 400: bad request, not an auth failure - 403: authorization issue, session is still valid - 404: ambiguous (session not found vs org/template not found share the same resource_not_found code) - 429: transient rate limit Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The shouldRetry logic was changed from is4xxError to isUnauthenticatedError, which inadvertently caused deterministic client errors (400, 403, 404) to retry up to 8 times over ~3 minutes. Restore the correct behavior: only retry on transient failures (5xx, network errors, 429 rate limits). Also update changeset description. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

The "remains signed in" test passes even without the fix due to a race condition — handleUnauthenticated is fire-and-forget and may not complete within the wait window. The remaining two tests (setActive surfaces error, no recursive handleUnauthenticated) are deterministic and sufficient. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

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

jacekradko · 2026-03-06T21:31:54Z

packages/shared/src/errors/helpers.ts

+ */
+export function isUnauthenticatedError(e: any): boolean {
+  const status = e?.status;
+  return status === 401 || status === 422;


jacekradko

I like it! Definitely a more correct approach to handling various 4XX status codes.

github-actions bot added the clerk-js label Mar 6, 2026

vercel bot deployed to Preview March 6, 2026 15:59 View deployment

vercel bot deployed to Preview March 6, 2026 16:04 View deployment

coderabbitai bot reviewed Mar 6, 2026

View reviewed changes

packages/clerk-js/src/core/clerk.ts Outdated Show resolved Hide resolved

Merge branch 'main' into bryce/fix-429-unauthenticated-handling

5cc0e7b

vercel bot deployed to Preview March 6, 2026 16:17 View deployment

github-actions bot added the integration label Mar 6, 2026

vercel bot deployed to Preview March 6, 2026 18:09 View deployment

vercel bot deployed to Preview March 6, 2026 18:52 View deployment

vercel bot deployed to Preview March 6, 2026 19:12 View deployment

vercel bot deployed to Preview March 6, 2026 19:17 View deployment

vercel bot deployed to Preview March 6, 2026 19:45 View deployment

fix(test): Add missing curly braces to satisfy lint rule

e47967a

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

vercel bot deployed to Preview March 6, 2026 20:05 View deployment

fix lint

f6b8b31

vercel bot deployed to Preview March 6, 2026 20:38 View deployment

lint

f11e4d4

vercel bot deployed to Preview March 6, 2026 21:03 View deployment

jacekradko reviewed Mar 6, 2026

View reviewed changes

jacekradko approved these changes Mar 6, 2026

View reviewed changes

brkalow merged commit 7fb870d into main Mar 7, 2026
41 checks passed

brkalow deleted the bryce/fix-429-unauthenticated-handling branch March 7, 2026 03:26

clerk-cookie mentioned this pull request Mar 6, 2026

ci(repo): Version packages #7984

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

fix(clerk-js): Do not treat 429 responses as authentication failures#8004
brkalow merged 11 commits intomainfrom
bryce/fix-429-unauthenticated-handling

brkalow commented Mar 6, 2026 •

edited

Loading

Uh oh!

vercel bot commented Mar 6, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Mar 6, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Mar 6, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Mar 6, 2026 •

edited

Loading

Reviews paused

Walkthrough

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

jacekradko Mar 6, 2026

Uh oh!

jacekradko left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

brkalow commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Telemetry evidence (7-day window)

Test plan

Summary by CodeRabbit

Uh oh!

vercel bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jacekradko Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

jacekradko left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

brkalow commented Mar 6, 2026 •

edited

Loading

vercel bot commented Mar 6, 2026 •

edited

Loading

changeset-bot bot commented Mar 6, 2026 •

edited

Loading

pkg-pr-new bot commented Mar 6, 2026 •

edited

Loading

coderabbitai bot commented Mar 6, 2026 •

edited

Loading