Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
docs(errors): document unclassified subscription auth failures as 503
Jack Rudenko7c83735e335a
diff --git a/ai-docs/architecture/adapters.md b/ai-docs/architecture/adapters.mdindex 21b55db6..a3e38720 100644--- a/ai-docs/architecture/adapters.md+++ b/ai-docs/architecture/adapters.md@@ -461,14 +461,26 @@ in one order:| connection | `classifyConnectionError` | none; the caller runs connection recovery first || terminal | `err.terminal === true` | 400 `invalid_request_error`, verdict `terminal`, `upstream_status` kept || transient | `upstreamStatus` 429 or 5xx, or `transient: true` | 429 for a 429, otherwise 503, verdict `transient` |-| unknown, subscription | anything else | as terminal |+| unknown, subscription | anything else | 503 `overloaded_error`, verdict `transient` (retried on the same hop, never walked) || unknown, metered | anything else | 401 at `refreshAuth` and `forceRefreshAuth` only; other sites rethrow |-`unknown` on a subscription is terminal, not transient (a deviation from the architecture's 503).-Connection faults are classified first and real transients carry a status, so what is left is-overwhelmingly a credential fault: Kimi's "No Kimi OAuth credentials found. Please run `claudish-login kimi` first." is a plain `Error`. Answered 503 it would hide behind about two minutes of-Claude Code's silent retries.+**The rule: a dead or unsubscribed credential is a terminal 400 that stops the chain; an+unclassified failure is a retryable 503.** It holds because the PRODUCERS say what their failure+is, through `auth/credentials/credential-error.ts` (`d86e3d86`): a missing login or a rejected+grant is `terminalCredentialError`, a token host's 429/5xx is `credentialHttpError` (transient,+with its `upstreamStatus`). Kimi's "No Kimi OAuth credentials found. Please run `claudish login+kimi` first." is therefore `terminal`, not `unknown`. What is still `unknown` is a failure nobody+classified, and for a subscription the conservative answer is retry: stopping a working plan with a+login instruction because a token host blinked is the worse error. (An earlier cut answered+`unknown` as terminal; it turned Grok's token-host 503 into a fatal "run `claudish login grok`".)++The producers that must keep this contract, and the first place a NEW subscription provider must+follow it: `auth/grok-oauth.ts`, `providers/grok/grok-credentials.ts`, `auth/kimi-oauth.ts`,+`auth/codex-oauth.ts`, `auth/antigravity-token.ts` (both the expiry and the forced refresh),+`auth/antigravity-user.ts`, `auth/oauth-manager.ts` (missing login), and the Muse Code mint and+core (`providers/meta-muse/`). A TRANSPORT must not swallow what they throw: a catch that returns+normally hands ComposedHandler nothing to classify (CLAUDE.md's transport-catch invariant). The+Codex and Kimi Code transports each had one, and both now rethrow (`ecbb92d1`, `2bf1f736`).All five auth sites in `composed-handler.ts` (`refreshAuth`, `getHeaders`, the primary fetch, theparameter-recovery re-fetch, `forceRefreshAuth`) use it, and so does a `recoverConnection` thatdiff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.tsindex 6af16953..220284ed 100644--- a/packages/cli/src/handlers/composed-handler.ts+++ b/packages/cli/src/handlers/composed-handler.ts@@ -753,10 +753,11 @@ export class ComposedHandler implements ModelHandler {/*** Answer a failure at a credential site that is NOT a connection fault- * (`auth-failure.ts`): a terminal one — and any unclassifiable one of a- * SUBSCRIPTION — as 400 with the terminal verdict, so the chain stops and the- * message lands inline; a transient one as 503/429 with the transient- * verdict, never 401.+ * (`auth-failure.ts`): a terminal one (a dead or unsubscribed login, as the+ * producer marked it) as 400 with the terminal verdict, so the chain stops and+ * the message lands inline; a transient one — and any unclassifiable one of a+ * SUBSCRIPTION — as 503/429 with the transient verdict, retried on the same+ * hop, never 401.** An unclassifiable failure of a METERED provider gets 401 only where* `meteredUnknown` is `"401"` (the refreshAuth and forceRefreshAuth catches,@@ -1390,10 +1391,10 @@ export class ComposedHandler implements ModelHandler {// hidden behind "API error · Retrying", and walked the chain.// - transient (the token host answered 5xx/429) → 503/429 with the// transient verdict, never 401: the same hop answers on retry.- // - unclassifiable: a SUBSCRIPTION → terminal 400 (Kimi's plain- // "run `claudish login kimi`" error lands inline); a METERED- // provider → 401 as before, so the chain may try a provider with- // another credential.+ // - unclassifiable: a SUBSCRIPTION → 503 with the transient verdict+ // (retried, never walked; a dead login is marked terminal by its+ // producer, `credential-error.ts`); a METERED provider → 401 as+ // before, so the chain may try a provider with another credential.const answered = this.answerAuthFailure(c, err, "401");if (answered) return answered;throw err;@@ -1461,7 +1462,7 @@ export class ComposedHandler implements ModelHandler {const conn = classifyConnectionError(err);if (!conn) {// A credential failure this site can place is answered here — terminal- // or a subscription's unclassifiable one as 400, transient as 503/429.+ // as 400; transient, or a subscription's unclassifiable one, as 503/429.// Anything else (a metered provider's unclassifiable throw) keeps its// existing route out of here untouched.const answered = this.answerAuthFailure(c, err, "rethrow");@@ -1997,10 +1998,10 @@ export class ComposedHandler implements ModelHandler {} catch {// Stats must never crash claudish}- // The same classifier as the refreshAuth catch: terminal (and a- // subscription's unclassifiable failure) → 400 with the terminal- // verdict; transient → 503/429; a metered provider's- // unclassifiable failure → 401 as before.+ // The same classifier as the refreshAuth catch: terminal → 400 with+ // the terminal verdict; transient, or a subscription's+ // unclassifiable failure → 503/429 with the transient verdict; a+ // metered provider's unclassifiable failure → 401 as before.const answered = this.answerAuthFailure(c, err, "401");if (answered) return answered;throw err;