From c88b96244fcf7e6235db220c758f5af5cc90552d Mon Sep 17 00:00:00 2001
From: Diego Rodrigues de Sa e Souza <diegosouza.pw@gmail.com>
Date: Sat, 8 Aug 2026 13:52:11 -0300
Subject: [PATCH] fix(providers): classify 400 out of extra usage as
 quota_exhausted for Anthropic OAuth (#9486)

Refs: base-red #9737
---
 changelog.d/fixes/9486-claude-400-quota.md |  1 +
 open-sse/config/errorConfig.ts             | 12 ++++
 tests/unit/repro-9486.test.ts              | 71 ++++++++++++++++++++++
 3 files changed, 84 insertions(+)
 create mode 100644 changelog.d/fixes/9486-claude-400-quota.md
 create mode 100644 tests/unit/repro-9486.test.ts

diff --git a/changelog.d/fixes/9486-claude-400-quota.md b/changelog.d/fixes/9486-claude-400-quota.md
new file mode 100644
index 0000000000..b410faf7d1
--- /dev/null
+++ b/changelog.d/fixes/9486-claude-400-quota.md
@@ -0,0 +1 @@
+- fix(providers): classify 400 out of extra usage as quota_exhausted for Anthropic OAuth
diff --git a/open-sse/config/errorConfig.ts b/open-sse/config/errorConfig.ts
index 8124c93f43..dcdf3bae9c 100644
--- a/open-sse/config/errorConfig.ts
+++ b/open-sse/config/errorConfig.ts
@@ -149,6 +149,18 @@ export const ERROR_RULES: ErrorRule[] = [
     backoff: true,
     reason: "quota_exhausted",
   },
+  {
+    id: "out_of_extra_usage",
+    text: "out of extra usage",
+    backoff: true,
+    reason: "quota_exhausted",
+  },
+  {
+    id: "extra_usage_required",
+    text: "extra usage required",
+    backoff: true,
+    reason: "quota_exhausted",
+  },
   { id: "capacity", text: "capacity", backoff: true, reason: "model_capacity" },
   { id: "overloaded", text: "overloaded", backoff: true, reason: "model_capacity" },
   { id: "high_demand", text: "high demand", backoff: true, reason: "model_capacity" },
diff --git a/tests/unit/repro-9486.test.ts b/tests/unit/repro-9486.test.ts
new file mode 100644
index 0000000000..3df80de635
--- /dev/null
+++ b/tests/unit/repro-9486.test.ts
@@ -0,0 +1,71 @@
+/**
+ * Issue #9486 — Anthropic OAuth returns HTTP 400 with "out of extra usage" in
+ * the error body when a tool-carrying request exceeds the account's usage quota.
+ * This should be classified as quota_exhausted (not generic bad_request), so the
+ * account fallback mechanism applies a proper cooldown and combo routing can
+ * skip to another target.
+ */
+import test from "node:test";
+import assert from "node:assert/strict";
+
+const { matchErrorRuleByText, findMatchingErrorRule, ERROR_RULES } =
+  await import("../../open-sse/config/errorConfig.ts");
+const { checkFallbackError, classifyErrorText } =
+  await import("../../open-sse/services/accountFallback.ts");
+const { RateLimitReason } = await import("../../open-sse/config/constants.ts");
+
+test("#9486 ERROR_RULES has a text rule for 'out of extra usage' → quota_exhausted", () => {
+  const rule = ERROR_RULES.find((r) => r.text === "out of extra usage");
+  assert.ok(rule, "expected a rule for 'out of extra usage'");
+  assert.equal(rule!.reason, "quota_exhausted");
+  // Should use backoff so the fallback path applies exponential scaling
+  assert.equal(rule!.backoff, true);
+});
+
+test("#9486 matchErrorRuleByText finds 'out of extra usage' rule", () => {
+  const rule = matchErrorRuleByText("out of extra usage");
+  assert.ok(rule, "expected a matching rule");
+  assert.equal(rule!.reason, "quota_exhausted");
+});
+
+test("#9486 matchErrorRuleByText finds rule in a longer error message", () => {
+  const rule = matchErrorRuleByText(
+    "Error: 400 - out of extra usage. You have exceeded your usage quota for this billing period."
+  );
+  assert.ok(rule, "expected a matching rule from longer message");
+  assert.equal(rule!.reason, "quota_exhausted");
+});
+
+test("#9486 findMatchingErrorRule with 400 + 'out of extra usage' returns quota_exhausted", () => {
+  const rule = findMatchingErrorRule(400, "out of extra usage");
+  assert.ok(rule, "expected a matching rule");
+  assert.equal(rule!.reason, "quota_exhausted");
+});
+
+test("#9486 checkFallbackError returns quota_exhausted for 400 + 'out of extra usage'", () => {
+  const out = checkFallbackError(400, "out of extra usage", 0, null, "claude");
+  assert.equal(out.shouldFallback, true);
+  assert.equal(out.reason, RateLimitReason.QUOTA_EXHAUSTED);
+  // Should get a non-zero cooldown (quota exhaustion is not transient)
+  assert.ok(out.cooldownMs > 0, `expected positive cooldown, got ${out.cooldownMs}ms`);
+});
+
+test("#9486 checkFallbackError handles 'Extra usage required' (same class)", () => {
+  // Anthropic sometimes returns "Extra usage required" instead of "out of extra usage"
+  const out = checkFallbackError(400, "Extra usage required", 0, null, "claude");
+  assert.equal(out.shouldFallback, true);
+  assert.equal(out.reason, RateLimitReason.QUOTA_EXHAUSTED);
+});
+
+test("#9486 classifyErrorText flags 'out of extra usage' as QUOTA_EXHAUSTED", () => {
+  const out = classifyErrorText("out of extra usage");
+  assert.equal(out, RateLimitReason.QUOTA_EXHAUSTED);
+});
+
+test("#9486 generic 400 without quota text still gets no fallback (regression guard)", () => {
+  // Regression guard: a plain 400 with no quota-related text must NOT trigger
+  // fallback, preserving the existing behavior for non-quota 400 errors.
+  const out = checkFallbackError(400, "Bad request: invalid JSON", 0, null, "claude");
+  assert.equal(out.shouldFallback, false);
+  assert.equal(out.reason, RateLimitReason.UNKNOWN);
+});
\ No newline at end of file