feat: improve 429 error handling AUTO-158

package.json

@@ -108,6 +108,8 @@
       "minimatch": "^10.2.1",
       "glob": "^11.0.0",
       "serialize-javascript": "^7.0.5"
-    }
+    },
+    "hono": "^4.12.26",
+    "undici": "^7.28.0"
   }
 }

src/lib/agent-client.ts

@@ -144,9 +144,10 @@ export class ProfileNotFoundError extends UpgradeError {
 }
 
 // Upgrade statuses where a one-shot retry cannot help: bad request (400),
-// bad auth (401), forbidden by plan/policy (403), or missing resource (404).
-// Retrying just wastes time and emits a misleading "second attempt failed".
-const NON_RETRYABLE_UPGRADE_STATUSES = new Set([400, 401, 403, 404]);
+// bad auth (401), forbidden by plan/policy (403), missing resource (404), or
+// concurrency limit (429). Retrying a 429 just opens another session and
+// stacks more lingering sessions against the same limit, so stop instead.
+const NON_RETRYABLE_UPGRADE_STATUSES = new Set([400, 401, 403, 404, 429]);
 
 export const isRetryableUpgradeError = (err: unknown): boolean => {
   if (err instanceof UpgradeError) {

src/lib/agent-format.ts

@@ -103,7 +103,7 @@ export const formatConnectError = (err: unknown): string => {
       case 403:
         return `Forbidden (403) — your plan does not include this feature${detail ? ` (server says: ${detail})` : ''}.`;
       case 429:
-        return `Concurrency limit reached (429)${detail ? `: ${detail}` : ''}. Wait for in-flight sessions to finish, or upgrade the plan.`;
+        return `Concurrency limit reached (429)${detail ? `: ${detail}` : ''}. Stop retrying — each new attempt opens another session and stacks more against the limit. Close any sessions you still have open (call browserless_agent with method "close"), wait for in-flight sessions to finish, or upgrade the plan, then start over.`;
       default: {
         const fallback = detail || err.statusMessage || '';
         return `Failed to connect to browser agent (HTTP ${err.statusCode})${fallback ? `: ${fallback}` : ''}.`;

test/lib/agent-client.spec.ts

@@ -234,17 +234,19 @@ describe('agent-client proxyFingerprint', () => {
 describe('agent-client isRetryableUpgradeError', () => {
   // The retry guard exists so the agent tool doesn't burn a second WS
   // handshake when the server already returned a definitive 4xx.
-  it('does not retry on 400/401/403/404', () => {
-    for (const status of [400, 401, 403, 404]) {
+  it('does not retry on 400/401/403/404/429', () => {
+    // 429 is non-retryable: a retry opens another session and stacks more
+    // lingering sessions against the same concurrency limit.
+    for (const status of [400, 401, 403, 404, 429]) {
       expect(
         isRetryableUpgradeError(new UpgradeError(status, 'msg', 'body')),
         `status=${status}`,
       ).to.equal(false);
     }
   });
 
-  it('retries on 5xx and 429 (transient)', () => {
-    for (const status of [429, 500, 502, 503]) {
+  it('retries on 5xx (transient)', () => {
+    for (const status of [500, 502, 503]) {
       expect(
         isRetryableUpgradeError(new UpgradeError(status, 'msg', 'body')),
         `status=${status}`,

test/tools/agent.spec.ts

@@ -394,7 +394,8 @@ describe('formatConnectError', () => {
       ),
     );
     expect(out).to.match(/^Concurrency limit reached \(429\)/);
-    expect(out).to.include('Wait for');
+    expect(out).to.include('Stop retrying');
+    expect(out).to.include('wait for');
   });
 
   it('falls back to a generic upgrade message for unrecognized statuses', () => {
@@ -461,7 +462,7 @@ describe('formatConnectError with proxy-injected errors', () => {
     const out = formatConnectError(
       new UpgradeError(429, 'Too Many Requests', ''),
     );
-    expect(out).to.match(/^Concurrency limit reached \(429\)\. Wait for/);
+    expect(out).to.match(/^Concurrency limit reached \(429\)\. Stop retrying/);
   });
 
   it('renders nginx HTML 502 body as cleaned text', () => {