@juspay/neurolink 9.87.1 → 9.87.3

package/dist/lib/server/routes/claudeProxyRoutes.js

@@ -23,7 +23,7 @@ import { withSpan } from "../../telemetry/withSpan.js";
 import { ProxyTracer, recordFallbackAttempt } from "../../proxy/proxyTracer.js";
 import { createRawStreamCapture } from "../../proxy/rawStreamCapture.js";
 import { relocateClientSystemIntoMessages } from "../../proxy/systemRelocation.js";
-import { logBodyCapture, logRequest, logRequestAttempt, logStreamError, } from "../../proxy/requestLogger.js";
+import { logBodyCapture, logRequest, logRequestAttempt, } from "../../proxy/requestLogger.js";
 import { createSSEInterceptor } from "../../proxy/sseInterceptor.js";
 import { createStreamTerminalOutcomeTracker, mergeStreamTerminalOutcome, } from "../../proxy/streamOutcome.js";
 import { isPermanentRefreshFailure, needsRefresh, persistTokens, refreshToken, } from "../../proxy/tokenRefresh.js";
@@ -91,12 +91,23 @@ const AUTH_REFRESH_MAX_COOLDOWN_MS = 5 * 60 * 1000;
  *  thinking from Opus models (which can exceed 5 minutes for large contexts). */
 const UPSTREAM_FETCH_TIMEOUT_MS = 15 * 60 * 1000; // 15 minutes
 const accountRuntimeState = new Map();
+/** Shared across requests so a concurrent burst gets at most two retries for
+ *  the account/window, rather than every request starting its own retry chain. */
+const transientRateLimitRetryBudgets = new Map();
+/** Pace requests that arrive while the last usable account has a short
+ * transient cooldown. This converts a local 429/retry storm into a bounded
+ * queue and avoids releasing every waiting request at the same millisecond. */
+const transientCooldownAdmissionSchedules = new Map();
 /** Track whether we've run the one-time startup prune. */
 let startupPruneDone = false;
 /** Default cooling period when retries are exhausted and upstream didn't
  *  provide a retry-after header. Short enough to recover quickly, long
  *  enough to avoid immediately hammering the same account. */
 const DEFAULT_COOLING_PERIOD_MS = 60_000;
+const MAX_TRANSIENT_QUEUE_WAIT_MS = 90_000;
+const MAX_TRANSIENT_TOTAL_QUEUE_WAIT_MS = 120_000;
+const TRANSIENT_ADMISSION_SPACING_MS = 250;
+const MAX_TRANSIENT_ADMISSION_SPREAD_MS = 15_000;
 /** Advance the primary account index when the current primary is exhausted
  *  (429 retries exhausted or auth failure). This is what makes fill-first work:
  *  we stick to one account until it's unusable. Only advances when the exhausted
@@ -159,6 +170,74 @@ function isAccountCooling(accountKey) {
     const state = accountRuntimeState.get(accountKey);
     return !!state?.coolingUntil && Date.now() < state.coolingUntil;
 }
+function claimTransientRateLimitRetry(accountKey, coolingUntil, now = Date.now()) {
+    let budget = transientRateLimitRetryBudgets.get(accountKey);
+    if (!budget || now >= budget.coolingUntil) {
+        budget = { coolingUntil, retriesClaimed: 0 };
+        transientRateLimitRetryBudgets.set(accountKey, budget);
+    }
+    else if (coolingUntil > budget.coolingUntil) {
+        budget.coolingUntil = coolingUntil;
+    }
+    if (budget.retriesClaimed >= MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES) {
+        return undefined;
+    }
+    budget.retriesClaimed += 1;
+    return budget.retriesClaimed;
+}
+function claimTransientCooldownAdmission(accountKey, coolingUntil, now = Date.now()) {
+    if (coolingUntil <= now) {
+        return 0;
+    }
+    if (coolingUntil - now > MAX_TRANSIENT_QUEUE_WAIT_MS) {
+        return undefined;
+    }
+    let schedule = transientCooldownAdmissionSchedules.get(accountKey);
+    if (!schedule || now >= schedule.coolingUntil) {
+        schedule = { coolingUntil, nextAdmissionAt: coolingUntil };
+        transientCooldownAdmissionSchedules.set(accountKey, schedule);
+    }
+    else if (coolingUntil > schedule.coolingUntil) {
+        schedule.coolingUntil = coolingUntil;
+        schedule.nextAdmissionAt = Math.max(schedule.nextAdmissionAt, coolingUntil);
+    }
+    const admissionAt = Math.max(now, schedule.coolingUntil, schedule.nextAdmissionAt);
+    if (admissionAt - schedule.coolingUntil > MAX_TRANSIENT_ADMISSION_SPREAD_MS) {
+        return undefined;
+    }
+    schedule.nextAdmissionAt = admissionAt + TRANSIENT_ADMISSION_SPACING_MS;
+    return admissionAt - now;
+}
+async function waitForTransientAccountAvailability(orderedAccounts) {
+    const deadline = Date.now() + MAX_TRANSIENT_TOTAL_QUEUE_WAIT_MS;
+    while (Date.now() < deadline) {
+        const available = orderedAccounts.filter((account) => !isAccountCooling(account.key));
+        if (available.length > 0) {
+            return available;
+        }
+        const now = Date.now();
+        const transientCandidate = orderedAccounts
+            .map((account) => ({
+            account,
+            state: getOrCreateRuntimeState(account.key),
+        }))
+            .filter(({ state }) => state.coolingReason === "transient" &&
+            state.coolingUntil !== undefined &&
+            state.coolingUntil > now)
+            .sort((a, b) => (a.state.coolingUntil ?? Number.POSITIVE_INFINITY) -
+            (b.state.coolingUntil ?? Number.POSITIVE_INFINITY))[0];
+        if (!transientCandidate?.state.coolingUntil) {
+            return [];
+        }
+        const waitMs = claimTransientCooldownAdmission(transientCandidate.account.key, transientCandidate.state.coolingUntil, now);
+        if (waitMs === undefined || now + waitMs > deadline) {
+            return [];
+        }
+        logger.always(`[proxy] all usable accounts are transiently cooling; queueing request for account=${transientCandidate.account.label} in ${waitMs}ms`);
+        await sleep(waitMs);
+    }
+    return [];
+}
 // ---------------------------------------------------------------------------
 // Quota-aware cooldown helpers
 // ---------------------------------------------------------------------------
@@ -645,13 +724,11 @@ function responseInfoFromStream(data) {
  * into the body.  Non-CC clients (Curator, custom apps) don't send these —
  * Anthropic rejects without them.
  */
-function polyfillOAuthBody(bodyStr, accountToken, snapshot, preferredSessionId) {
+function polyfillOAuthBody(bodyStr, accountToken, snapshot, isClaudeClientRequest, preferredSessionId) {
     try {
         const parsed = JSON.parse(bodyStr);
-        // Billing header block (required by Anthropic for OAuth)
-        // NOTE: This block MUST be deterministic (no random values) to preserve
-        // Anthropic's prompt caching prefix chain. We keep the real Claude Code
-        // version/entrypoint shape when present, but stabilize the volatile cch.
+        // Billing header block synthesized for clients that do not already provide
+        // the genuine Claude Code identity shape.
         const agentBlock = {
             type: "text",
             text: snapshot?.body?.agentBlock ||
@@ -661,11 +738,11 @@ function polyfillOAuthBody(bodyStr, accountToken, snapshot, preferredSessionId)
         //
         // The subscription/OAuth path only accepts a `system` it recognises as the
         // genuine Claude Code prompt. A real CC client sends its own billing + agent
-        // identity blocks alongside the canonical prompt — we keep those in place and
-        // just stabilise the volatile billing `cch`. A custom client (Curator) sends
-        // its own arbitrary system prompt with NO agent block; left in `system` it is
-        // rejected as `rate_limit_error: "Error"`, so we relocate it into the message
-        // stream and send only the recognised billing + agent blocks as `system`.
+        // identity blocks alongside the canonical prompt, which must pass through
+        // unchanged. A custom client (Curator) sends its own arbitrary system prompt
+        // with NO agent block; left in `system` it is rejected as
+        // `rate_limit_error: "Error"`, so we relocate it into the message stream and
+        // send only the recognised billing + agent blocks as `system`.
         if (parsed.system) {
             if (typeof parsed.system === "string") {
                 parsed.system = [{ type: "text", text: parsed.system }];
@@ -679,28 +756,28 @@ function polyfillOAuthBody(bodyStr, accountToken, snapshot, preferredSessionId)
                     type: "text",
                     text: buildStableClaudeCodeBillingHeader(parsed.system[billingIdx]?.text ?? snapshot?.body?.billingHeader),
                 };
-                // A genuine Claude Code client supplies its own agent-identity block;
-                // a custom client (Curator) does not.
-                const isClaudeCodeClient = agentIdx >= 0;
-                // Strip billing/agent from their positions (reverse order so indices
-                // stay valid). What remains is the client's "extra" system content.
-                const indicesToRemove = [billingIdx, agentIdx]
-                    .filter((i) => i >= 0)
-                    .sort((a, b) => b - a);
-                for (const idx of indicesToRemove) {
-                    parsed.system.splice(idx, 1);
-                }
-                if (!isClaudeCodeClient && parsed.system.length > 0) {
-                    // Non-CC client: relocate its system into the message stream so the
-                    // subscription/OAuth path accepts the request, then send only the
-                    // recognised billing + agent blocks as `system`.
-                    relocateClientSystemIntoMessages(parsed, parsed.system);
-                    parsed.system = [billingBlock, agentBlock];
+                const hasClaudeCodeSystemIdentity = isClaudeClientRequest && agentIdx >= 0;
+                if (hasClaudeCodeSystemIdentity) {
+                    // Claude Code's subagent billing marker, block order, and cache
+                    // controls are part of the accepted request shape. Preserve every
+                    // supplied block exactly; only synthesize a billing block if absent.
+                    if (billingIdx < 0) {
+                        parsed.system.unshift(billingBlock);
+                    }
                 }
                 else {
-                    // Genuine Claude Code (or no extra blocks): keep the recognised system
-                    // and append the deterministic billing + agent blocks at the end.
-                    parsed.system = [...parsed.system, billingBlock, agentBlock];
+                    // Strip generated identity blocks before relocating a custom
+                    // client's actual system instructions into the message stream.
+                    const indicesToRemove = [billingIdx, agentIdx]
+                        .filter((i) => i >= 0)
+                        .sort((a, b) => b - a);
+                    for (const idx of indicesToRemove) {
+                        parsed.system.splice(idx, 1);
+                    }
+                    if (parsed.system.length > 0) {
+                        relocateClientSystemIntoMessages(parsed, parsed.system);
+                    }
+                    parsed.system = [billingBlock, agentBlock];
                 }
             }
         }
@@ -2012,7 +2089,7 @@ async function handleAnthropicSuccessfulResponse(args) {
     });
 }
 async function handleAnthropicStreamingSuccessResponse(args) {
-    const { ctx, body, account, accountState: _accountState, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
+    const { account, accountState: _accountState, response, responseHeaders, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
     if (!response.body) {
         upstreamSpan?.end();
         tracer?.setError("stream_error", "No response body from upstream");
@@ -2093,17 +2170,9 @@ async function handleAnthropicStreamingSuccessResponse(args) {
                 controller.enqueue(value);
             }
             catch (streamErr) {
-                const errMsg = streamErr instanceof Error ? streamErr.message : String(streamErr);
+                const errMsg = describeTransportError(streamErr);
                 logger.always(`[proxy] mid-stream error account=${account.label}: ${errMsg}`);
                 streamOutcomeTracker.fail(errMsg);
-                logStreamError({
-                    timestamp: new Date().toISOString(),
-                    requestId: ctx.requestId,
-                    account: account.label,
-                    model: body.model,
-                    errorMessage: errMsg,
-                    durationMs: Date.now() - fetchStartMs,
-                });
                 if (!mainStreamClosed) {
                     mainStreamClosed = true;
                     const errorEvent = `event: error\ndata: ${JSON.stringify({ type: "error", error: { type: "api_error", message: `Upstream stream interrupted: ${errMsg}` } })}\n\n`;
@@ -2469,7 +2538,7 @@ async function handleAnthropicJsonSuccessResponse(args) {
     return { response: responseJson };
 }
 async function handleAnthropicSuccessfulRetryResponse(args) {
-    const { ctx, body, account, accountState, retryResp, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
+    const { body, account, accountState, retryResp, tracer, requestStartTime, fetchStartMs, attemptNumber, finalBodyStr, upstreamSpan, logProxyBody, logFinalRequest, } = args;
     const retryQuota = parseQuotaHeaders(retryResp.headers);
     if (retryQuota) {
         // Keep the auth-retry success path in parity with the main success path:
@@ -2514,17 +2583,9 @@ async function handleAnthropicSuccessfulRetryResponse(args) {
                     controller.enqueue(value);
                 }
                 catch (streamErr) {
-                    const errMsg = streamErr instanceof Error ? streamErr.message : String(streamErr);
+                    const errMsg = describeTransportError(streamErr);
                     logger.always(`[proxy] mid-stream error (auth-retry) account=${account.label}: ${errMsg}`);
                     streamOutcomeTracker.fail(errMsg);
-                    logStreamError({
-                        timestamp: new Date().toISOString(),
-                        requestId: ctx.requestId,
-                        account: account.label,
-                        model: body.model,
-                        errorMessage: errMsg,
-                        durationMs: Date.now() - fetchStartMs,
-                    });
                     if (!retryStreamClosed) {
                         retryStreamClosed = true;
                         const errorEvent = `event: error\ndata: ${JSON.stringify({ type: "error", error: { type: "api_error", message: `Upstream stream interrupted: ${errMsg}` } })}\n\n`;
@@ -2716,15 +2777,36 @@ async function handleAnthropicAuthRetry(args) {
             authRetryError = `retry ${authRetry + 1}/${MAX_AUTH_RETRIES} failed with status ${retryStatus}`;
             currentLastError = retryBody;
             logger.debug(`[proxy] retry ${authRetry + 1} failed: ${retryStatus} ${retryBody.substring(0, 120)}`);
-            recordAttemptError(account.label, account.type, retryStatus);
-            // A real rate-limit 429 rotates accounts. But an anti-abuse / construction
-            // 429 (no rate-limit headers, body "Error") is NOT a real rate limit:
-            // advancing the primary or rotating cannot help and only burns quota. Skip
-            // the rotate path for it so it falls through to the terminal error return
-            // below, surfacing the truthful upstream error — mirroring the initial
-            // fetch path's fast-fail (isAntiAbuseConstruction429).
             if (retryStatus === 429 &&
-                !isAntiAbuseConstruction429(retryRespHeaders, retryBody)) {
+                isAntiAbuseConstruction429(retryRespHeaders, retryBody)) {
+                logger.always(`[proxy] ← 429 account=${account.label} anti-abuse/construction rejection after OAuth refresh — returning non-retryable request error`);
+                logAttempt(429, "construction_rejection", retryBody);
+                tracer?.setError("construction_rejection", retryBody.slice(0, 500));
+                currentUpstreamSpan?.end();
+                return {
+                    response: finalizeAnthropicTerminalFetchError({
+                        terminalError: buildAnthropicConstructionRejectionTerminalError(),
+                        account,
+                        tracer,
+                        requestStartTime,
+                        attemptNumber,
+                        logProxyBody,
+                        logFinalRequest,
+                    }),
+                    continueLoop: false,
+                    lastError: retryBody,
+                    authFailureMessage: currentAuthFailureMessage,
+                    sawRateLimit: currentSawRateLimit,
+                    sawTransientFailure: currentSawTransientFailure,
+                    sawNetworkError: currentSawNetworkError,
+                    upstreamSpan: undefined,
+                };
+            }
+            recordAttemptError(account.label, account.type, retryStatus);
+            // Construction rejections return through the terminal 400 path above.
+            // Every 429 reaching this branch is a genuine rate limit and must cool
+            // the account according to its reset window before rotating.
+            if (retryStatus === 429) {
                 currentSawRateLimit = true;
                 // Cool the account per its real reset window before rotating, so a
                 // session/weekly-exhausted account isn't re-selected next request.
@@ -2862,6 +2944,22 @@ function buildAnthropicTerminalErrorResponse(args) {
         return clientError;
     }
 }
+function finalizeAnthropicTerminalFetchError(args) {
+    const { terminalError, account, tracer, requestStartTime, attemptNumber, logProxyBody, logFinalRequest, } = args;
+    recordFinalError(terminalError.status, account.label, account.type);
+    tracer?.end(terminalError.status, Date.now() - requestStartTime);
+    return buildAnthropicTerminalErrorResponse({
+        responseStatus: terminalError.status,
+        account,
+        errBody: terminalError.body,
+        errRespHeaders: terminalError.headers,
+        requestStartTime,
+        attemptNumber,
+        logProxyBody,
+        logFinalRequest,
+        errorType: terminalError.errorType,
+    });
+}
 async function handleAnthropicNonOkResponse(args) {
     const { response, account, accountState, enabledAccounts, orderedAccounts, tracer, requestStartTime, fetchStartMs, attemptNumber, logAttempt, logProxyBody, logFinalRequest, lastError, authFailureMessage, sawTransientFailure, invalidRequestFailure, } = args;
     let currentLastError = lastError;
@@ -3271,7 +3369,7 @@ async function prepareAnthropicAccountAttempt(args) {
         }
     }
     const buildUpstreamBody = (token) => isOAuth
-        ? polyfillOAuthBody(bodyStr, token, snapshot, headers["x-claude-code-session-id"])
+        ? polyfillOAuthBody(bodyStr, token, snapshot, isClaudeClientRequest, headers["x-claude-code-session-id"])
         : { bodyStr };
     const polyfilledBody = buildUpstreamBody(account.token);
     if (isOAuth &&
@@ -3325,7 +3423,7 @@ async function prepareAnthropicAccountAttempt(args) {
  * "Error" and which carries NONE of the real rate-limit headers (no retry-after,
  * no anthropic-ratelimit-*). This is NOT a capacity limit — retrying or rotating
  * accounts cannot fix it and only burns quota, so the caller must fail fast and
- * surface the truthful upstream error instead of "all accounts rate-limited".
+ * return a non-retryable request error instead of "all accounts rate-limited".
  */
 function isAntiAbuseConstruction429(headers, body) {
     const hasRetryAfter = !!headers["retry-after"];
@@ -3335,6 +3433,14 @@ function isAntiAbuseConstruction429(headers, body) {
     }
     return (body.includes("rate_limit_error") && /"message"\s*:\s*"Error"/.test(body));
 }
+function buildAnthropicConstructionRejectionTerminalError() {
+    return {
+        status: 400,
+        body: JSON.stringify(buildClaudeError(400, "Anthropic rejected the OAuth request shape. This is not an account rate limit.", "invalid_request_error")),
+        headers: { "content-type": "application/json" },
+        errorType: "construction_rejection",
+    };
+}
 async function fetchAnthropicAccountResponse(args) {
     const { url, headers, finalBodyStr, account, accountState: _accountState2, enabledAccounts: _enabledAccounts, orderedAccounts: _orderedAccounts, tracer, logAttempt, logProxyBody, fetchStartMs, attemptNumber, currentLastError, currentSawRateLimit, currentSawNetworkError, upstreamSpan, } = args;
     let lastError = currentLastError;
@@ -3374,9 +3480,7 @@ async function fetchAnthropicAccountResponse(args) {
         };
     }
     if (response.status === 429) {
-        sawRateLimit = true;
         const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
-        recordAttemptError(account.label, account.type, 429);
         // Capture full response headers and body for diagnostics (parity with
         // handleAnthropicNonOkResponse which does this for all other error statuses).
         const errRespHeaders = {};
@@ -3407,28 +3511,24 @@ async function fetchAnthropicAccountResponse(args) {
         });
         // Anti-abuse / request-construction 429 (no rate-limit headers, body
         // "Error"): rotating accounts cannot help and only burns quota. Fail fast
-        // and surface the truthful upstream error instead of the misleading
-        // "all accounts rate-limited" after 44 wasted attempts.
+        // and return a non-retryable request error instead of prompting the client
+        // to repeat the same malformed request as a genuine rate limit.
         if (isAntiAbuseConstruction429(errRespHeaders, String(lastError))) {
-            logger.always(`[proxy] ← 429 account=${account.label} anti-abuse/construction rejection (no ratelimit headers, body="Error") — NOT a real rate limit; returning upstream error without rotating`);
+            logger.always(`[proxy] ← 429 account=${account.label} anti-abuse/construction rejection (no ratelimit headers, body="Error") — NOT a real rate limit; returning non-retryable request error`);
             logAttempt(429, "construction_rejection", String(lastError));
             tracer?.setError("construction_rejection", String(lastError).slice(0, 500));
             currentUpstreamSpan?.end();
-            const passthrough = new Response(String(lastError), {
-                status: 429,
-                headers: {
-                    "content-type": errRespHeaders["content-type"] ?? "application/json",
-                },
-            });
             return {
                 continueLoop: false,
-                response: passthrough,
+                terminalError: buildAnthropicConstructionRejectionTerminalError(),
                 lastError,
                 sawRateLimit,
                 sawNetworkError,
                 upstreamSpan: undefined,
             };
         }
+        sawRateLimit = true;
+        recordAttemptError(account.label, account.type, 429);
         // Parse the unified-window quota headers (present on real rate-limit 429s)
         // and derive a reset-aware cooldown plan. This is the fix for "kept
         // hammering the 5h/7d-exhausted account instead of switching": on an
@@ -3468,6 +3568,9 @@ async function fetchAnthropicAccountResponse(args) {
         upstreamSpan: currentUpstreamSpan,
     };
 }
+function shouldAttemptClaudeFallback(loopState) {
+    return loopState.invalidRequestFailure === null;
+}
 async function handleAnthropicRoutedClaudeRequest(args) {
     const { ctx, body, modelRouter, tracer, requestStartTime, accountStrategy, buildLoggedClaudeError, logProxyBody, logFinalRequest, } = args;
     const parsedRequest = parseClaudeRequest(body);
@@ -3507,7 +3610,16 @@ async function handleAnthropicRoutedClaudeRequest(args) {
     // is cooling, report the earliest persisted retry time without an upstream
     // call; restarting the proxy must not erase or bypass this quarantine.
     const nonCoolingAccounts = orderedAccounts.filter((a) => !isAccountCooling(a.key));
-    const effectiveAccounts = nonCoolingAccounts;
+    let effectiveAccounts = nonCoolingAccounts;
+    // If every usable account is cooling and the soonest recovery is a short
+    // transient burst cooldown, hold this request and pace its admission instead
+    // of returning a proxy-local 429 that makes the client retry in a herd. The
+    // helper rechecks because an in-flight retry can extend the cooldown while
+    // this request is waiting.
+    if (effectiveAccounts.length === 0) {
+        effectiveAccounts =
+            await waitForTransientAccountAvailability(orderedAccounts);
+    }
     if (effectiveAccounts.length === 0 && orderedAccounts.length > 0) {
         const coolingStates = orderedAccounts.map((account) => getOrCreateRuntimeState(account.key));
         const hasRateLimitCooldown = coolingStates.some((state) => state.coolingReason !== "auth");
@@ -3590,6 +3702,17 @@ async function handleAnthropicRoutedClaudeRequest(args) {
             loopState.lastError = fetchResult.lastError;
             loopState.sawRateLimit = fetchResult.sawRateLimit;
             loopState.sawNetworkError = fetchResult.sawNetworkError;
+            if (fetchResult.terminalError) {
+                return finalizeAnthropicTerminalFetchError({
+                    terminalError: fetchResult.terminalError,
+                    account,
+                    tracer,
+                    requestStartTime,
+                    attemptNumber: loopState.attemptNumber,
+                    logProxyBody,
+                    logFinalRequest,
+                });
+            }
             if (fetchResult.continueLoop || !fetchResult.response) {
                 // Genuine 429 (carries a cooldown plan derived from quota headers).
                 if (fetchResult.cooldownPlan) {
@@ -3601,32 +3724,41 @@ async function handleAnthropicRoutedClaudeRequest(args) {
                             // Non-fatal: routing already has the in-memory snapshot.
                         });
                     }
-                    // Transient burst (window still allowed): a couple of jittered
-                    // same-account retries before giving up. Exhaustion plans set
-                    // rotateImmediately, so retrySameAccount is false and we skip this.
+                    // Publish the cooldown before retrying so requests arriving behind
+                    // this one skip the throttled account instead of joining the burst.
+                    let cooldownExtended = false;
+                    if (!accountState.coolingUntil ||
+                        plan.coolingUntil > accountState.coolingUntil) {
+                        accountState.coolingUntil = plan.coolingUntil;
+                        accountState.coolingReason = plan.reason;
+                        cooldownExtended = true;
+                    }
+                    if (cooldownExtended) {
+                        await saveAccountCooldown(account.key, accountState.coolingUntil, accountState.coolingReason ?? plan.reason).catch(() => {
+                            // Non-fatal: routing already has the in-memory cooldown.
+                        });
+                    }
+                    // Transient retries are budgeted across all concurrent requests for
+                    // this account/window. Exhaustion plans rotate immediately and never
+                    // claim this budget.
+                    const sharedRetrySlot = fetchResult.retrySameAccount
+                        ? claimTransientRateLimitRetry(account.key, plan.coolingUntil)
+                        : undefined;
                     if (fetchResult.retrySameAccount &&
                         fetchResult.retryAfterMs !== undefined &&
-                        rateLimitSameAccountRetries < MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES) {
+                        rateLimitSameAccountRetries < MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES &&
+                        sharedRetrySlot !== undefined) {
                         rateLimitSameAccountRetries += 1;
                         const base = Math.min(fetchResult.retryAfterMs || 1_000, MAX_RATE_LIMIT_RETRY_DELAY_MS);
-                        // Cap AFTER jitter so the final sleep never exceeds the cap.
-                        const delayMs = Math.min(MAX_RATE_LIMIT_RETRY_DELAY_MS, jitteredDelay(base));
-                        logger.always(`[proxy] retrying same account=${account.label} after transient 429 (${rateLimitSameAccountRetries}/${MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES}) in ${delayMs}ms`);
+                        // Stagger the two shared slots, then cap after jitter so the final
+                        // sleep never exceeds the configured maximum.
+                        const delayMs = Math.min(MAX_RATE_LIMIT_RETRY_DELAY_MS, jitteredDelay(base * sharedRetrySlot));
+                        logger.always(`[proxy] retrying same account=${account.label} after transient 429 (shared slot ${sharedRetrySlot}/${MAX_RATE_LIMIT_SAME_ACCOUNT_RETRIES}) in ${delayMs}ms`);
                         await sleep(delayMs);
                         continue;
                     }
-                    // Exhaustion, or transient retries used up: park the account until
-                    // its ACTUAL reset (5h/7d) — no 60s hardcap — and rotate. Extend-only
-                    // so a concurrent short transient plan can't shorten a longer weekly
-                    // cooldown already set by another in-flight request.
-                    if (!accountState.coolingUntil ||
-                        plan.coolingUntil > accountState.coolingUntil) {
-                        accountState.coolingUntil = plan.coolingUntil;
-                        accountState.coolingReason = plan.reason;
-                    }
-                    await saveAccountCooldown(account.key, accountState.coolingUntil ?? plan.coolingUntil, accountState.coolingReason ?? plan.reason).catch(() => {
-                        // Non-fatal: routing already has the in-memory cooldown.
-                    });
+                    // Exhaustion, or the shared transient retry budget being used up:
+                    // rotate while the already-published cooldown remains active.
                     advancePrimaryIfCurrent(account.key, enabledAccounts.length, orderedAccounts[0]?.key);
                     logger.always(`[proxy] account=${account.label} rate-limited (${plan.reason}); cooling ~${minutesUntil(plan.coolingUntil, Date.now())}m until ${new Date(plan.coolingUntil).toISOString()}, rotating`);
                     continue accountLoop;
@@ -3768,32 +3900,37 @@ async function handleAnthropicRoutedClaudeRequest(args) {
     if (loopState.attemptNumber === 0) {
         acctSelectionSpan?.end();
     }
-    const configuredFallbackResult = await tryConfiguredClaudeFallbackChain({
-        ctx,
-        body,
-        parsedFallbackRequest: parsedRequest,
-        modelRouter,
-        tracer,
-        requestStartTime,
-        logProxyBody,
-        logFinalRequest,
-    });
-    if (configuredFallbackResult.response) {
-        return configuredFallbackResult.response;
-    }
-    // Try auto-provider fallback when the configured chain didn't produce a
-    // response (either no chain configured, or all entries failed/deduped).
-    if (!loopState.sawRateLimit) {
-        const autoFallbackResponse = await tryAutoClaudeFallback({
+    // Deterministic invalid requests (for example, prompt-too-long) cannot be
+    // repaired by changing providers. Preserve the authoritative Anthropic 400
+    // rather than delaying it or returning unrelated fallback output.
+    if (shouldAttemptClaudeFallback(loopState)) {
+        const configuredFallbackResult = await tryConfiguredClaudeFallbackChain({
             ctx,
             body,
+            parsedFallbackRequest: parsedRequest,
+            modelRouter,
             tracer,
             requestStartTime,
             logProxyBody,
             logFinalRequest,
         });
-        if (autoFallbackResponse) {
-            return autoFallbackResponse;
+        if (configuredFallbackResult.response) {
+            return configuredFallbackResult.response;
+        }
+        // Try auto-provider fallback when the configured chain didn't produce a
+        // response (either no chain configured, or all entries failed/deduped).
+        if (!loopState.sawRateLimit) {
+            const autoFallbackResponse = await tryAutoClaudeFallback({
+                ctx,
+                body,
+                tracer,
+                requestStartTime,
+                logProxyBody,
+                logFinalRequest,
+            });
+            if (autoFallbackResponse) {
+                return autoFallbackResponse;
+            }
         }
     }
     return buildClaudeAnthropicFailureResponse({
@@ -4077,6 +4214,26 @@ function getErrorCode(error) {
     const causeCode = cause.code;
     return typeof causeCode === "string" ? causeCode : undefined;
 }
+function describeTransportError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!error || typeof error !== "object") {
+        return message;
+    }
+    const cause = error.cause;
+    const causeMessage = cause instanceof Error
+        ? cause.message
+        : cause && typeof cause === "object"
+            ? String(cause.message ?? "")
+            : "";
+    const code = getErrorCode(error);
+    const detail = [
+        code,
+        causeMessage && causeMessage !== message && causeMessage,
+    ]
+        .filter(Boolean)
+        .join(": ");
+    return detail ? `${message} (${detail})` : message;
+}
 /**
  * Determine whether a thrown fetch error is a transient connectivity issue.
  */
@@ -4236,10 +4393,23 @@ export const __testHooks = {
     },
     resetAllRuntimeState: () => {
         accountRuntimeState.clear();
+        transientRateLimitRetryBudgets.clear();
+        transientCooldownAdmissionSchedules.clear();
         primaryAccountIndex = 0;
         lastKnownAccountCount = 0;
         configuredPrimaryAccountKey = undefined;
         configuredAccountAllowlist = undefined;
     },
+    polyfillOAuthBody: (bodyStr, isClaudeClientRequest) => polyfillOAuthBody(bodyStr, "test-account-token", null, isClaudeClientRequest),
+    isAntiAbuseConstruction429,
+    fetchAnthropicAccountResponse,
+    finalizeAnthropicTerminalFetchError,
+    handleAnthropicAuthRetry,
+    handleAnthropicStreamingSuccessResponse,
+    claimTransientRateLimitRetry,
+    claimTransientCooldownAdmission,
+    waitForTransientAccountAvailability,
+    describeTransportError,
+    shouldAttemptClaudeFallback,
 };
 //# sourceMappingURL=claudeProxyRoutes.js.map

package/dist/lib/types/proxy.d.ts

@@ -586,6 +586,10 @@ export type AccountCooldownPlan = {
      *  burst), a small number of jittered same-account retries is allowed first. */
     rotateImmediately: boolean;
 };
+export type TransientRateLimitRetryBudget = {
+    coolingUntil: number;
+    retriesClaimed: number;
+};
 export type AnthropicUpstreamFetchResult = {
     continueLoop: boolean;
     retrySameAccount?: boolean;
@@ -595,6 +599,15 @@ export type AnthropicUpstreamFetchResult = {
     cooldownPlan?: AccountCooldownPlan;
     /** Quota snapshot parsed from the response headers (429 or success), if present. */
     quota?: AccountQuota;
+    /** A terminal upstream rejection already captured and classified by the
+     *  fetch layer. The route must finalize it directly instead of feeding it
+     *  through the generic non-OK handler a second time. */
+    terminalError?: {
+        status: number;
+        body: string;
+        headers: Record<string, string>;
+        errorType: "construction_rejection";
+    };
     response?: Response;
     lastError: unknown;
     sawRateLimit: boolean;

package/dist/lib/types/safeFetch.d.ts

@@ -3,6 +3,15 @@
  *
  * Runtime helper lives in `src/lib/utils/safeFetch.ts`.
  */
+/**
+ * One validated address the pinned connect layer is allowed to dial.
+ * Produced by `ssrfGuard.ts:validateAndResolveUrl`, consumed by
+ * `safeFetch.ts:buildPinnedAgent`.
+ */
+export type PinnedAddress = {
+    ip: string;
+    family: 4 | 6;
+};
 export type SafeDownloadOptions = {
     /** Hard cap on response size in bytes. Pass MAX_VIDEO_BYTES/MAX_AUDIO_BYTES/MAX_IMAGE_BYTES from sizeGuard. */
     maxBytes: number;