Skip to content

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.md
index 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, the
parameter-recovery re-fetch, `forceRefreshAuth`) use it, and so does a `recoverConnection` that
diff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.ts
index 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;