feat(e2e): add rate-limit retry for backend API calls

[jacekradko]

Summary

• Adds a transparent rate-limit retry wrapper (withRateLimitRetry) around the ClerkClient used in integration test setup/teardown
• Wraps all async BAPI calls (user creation, org management, etc.) with automatic retry on HTTP 429 responses
• Uses exponential backoff with jitter, respects Retry-After headers (capped at 30s), max 5 retries
• Applied at the single createClerkClient call site in testUtils/index.ts — zero changes to individual service files or tests

Motivation

Multiple concurrent CI runs share the same Clerk development instances, causing 429 rate limit errors that fail integration tests several times a day. Instead of failing, tests will now automatically retry with backoff, logging [Rate Limit] Retry 1/5 for users.createUser, waiting 1234ms for CI observability.

Test plan

• pnpm build passes
• Monitor CI logs for [Rate Limit] Retry messages to confirm the wrapper activates on real 429s
• Verify reduction in 429-related test failures over the next few days

Summary by CodeRabbit

• Chores
  • Added automatic retry behavior for rate-limited API requests using exponential backoff with jitter and configurable caps.
  • Wrapped client initialization so API calls automatically retry on 429 responses, preserving request context for logging.
  • Added end-of-run reporting to surface rate-limit retry statistics.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1e7b53e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Mar 14, 2026 2:32pm

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

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

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 1e7b53e

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6271b03e-ea4b-4c7f-ac1d-a8fd6b809977

📥 Commits

Reviewing files that changed from the base of the PR and between c173fb8 and da6b998.

📒 Files selected for processing (2)

• integration/testUtils/rateLimitedClerkClient.ts
• integration/tests/global.teardown.ts

---

📝 Walkthrough

Walkthrough

Adds a new rate-limited retry module integration/testUtils/rateLimitedClerkClient.ts exporting withRateLimitRetry(client), which returns a Proxy that retries Promise-returning ClerkClient API calls on 429 responses using exponential backoff, jitter, a max retry count, and honoring retryAfter. The test utilities index now wraps the Clerk client with withRateLimitRetry. The global teardown imports and calls printRateLimitSummary() to report retry statistics.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding rate-limit retry logic for backend API calls in E2E tests. It is concise, specific, and directly reflects the primary objective of the changeset.

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

📝 Coding Plan

• Generate coding plan for human review comments

---

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