Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* One classifier for every failure that reaches a credential site, and one way
* to answer it.
*
* ## The rule (project owner, 2026-10-16, amended 2026-10-21)
*
* - A TERMINAL credential failure of a SUBSCRIPTION provider answers 400 with
* its message and the terminal verdict. An explicit spec stops there and the
* user is told to log in. In a routing chain, `FallbackHandler.handle` moves
* on to the next hop, metered included, and says so on stderr with the next
* hop's billing (2026-10-21: an expired key must not block the chain; a
* metered key the user configured is consent to be billed by it).
* - A TRANSIENT failure (network fault, 5xx, 429) never becomes a 401. A 401 is
* the one status `FallbackHandler.isRetryableError` reads as "try another
* credential", so a blip answered 401 walked the chain mid-outage.
*
* ## Why a header carries the verdict
*
* The status alone cannot: a terminal failure is answered 400 so Claude Code
* shows it inline instead of retrying it behind "API error · Retrying", and a
* 400 carrying `upstream_status: 401` is exactly what `isRetryableError`'s
* remap recovery reads as retryable. So the verdict rides
* {@link AUTH_VERDICT_HEADER}, which `isRetryableError` reads BEFORE any status
* or wording rule — the same structural pattern as the connection-fault marker
* (`recovery-marker.ts`), and unforgeable for the same reason: every non-ok
* response of `ComposedHandler` is a `c.json(...)` whose headers Hono builds
* from nothing.
*
* ## The order of classification
*
* connection → terminal → transient → unknown. A connection fault is never
* answered here at all: the caller runs connection recovery first, and only a
* failure recovery could not place comes back.
*
* The producers say what their failure is (`auth/credentials/credential-error.ts`):
* a missing login or a rejected grant is `terminal`, a token host's 429/5xx is
* `transient` with its status. What is left — `unknown` — is a failure nobody
* classified, and on a SUBSCRIPTION it is answered as RETRYABLE (503, verdict
* transient), never fatal: stopping a working subscription with a login
* instruction because a token host blinked is the worse error of the two.
*/
import type { Context } from "hono";
import type { ContentfulStatusCode } from "hono/utils/http-status";
import { redactForClient } from "../../redact.js";
import { wrapAnthropicError } from "./anthropic-error.js";
import { classifyConnectionError } from "./connection-error.js";
import { hasModelUnsupportedWording } from "./model-unsupported.js";
import { isQuotaExhaustionError } from "./quota-exhaustion.js";
/** The header name. Referenced by name in no other file — import this. */
export const AUTH_VERDICT_HEADER = "x-claudish-auth-verdict";
/**
* - `terminal`: the credential cannot succeed on retry. A metered hop stops the chain
* here; a subscription hop is moved past, with a notice (`FallbackHandler`).
* - `transient`: retrying the SAME hop is the remedy; the chain must not walk.
*/
export type AuthVerdict = "terminal" | "transient";
/** The headers a response with this verdict carries. */
export function authVerdictHeaders(verdict: AuthVerdict): Record<string, string> {
return { [AUTH_VERDICT_HEADER]: verdict };
}
/** The verdict a header bag carries, if any. Tolerates `undefined` and non-Headers values. */
export function authVerdict(headers: Headers | undefined | null): AuthVerdict | undefined {
try {
const value = headers?.get(AUTH_VERDICT_HEADER);
return value === "terminal" || value === "transient" ? value : undefined;
} catch {
return undefined;
}
}
export type AuthFailure =
| { kind: "connection"; conn: NonNullable<ReturnType<typeof classifyConnectionError>> }
| { kind: "transient"; status: number; message: string }
| { kind: "terminal"; message: string; upstreamStatus?: number }
| { kind: "unknown"; message: string };
/**
* Whether an upstream 401/403 rejects the CREDENTIAL — a dead, revoked or
* unsubscribed login — rather than this one request.
*
* The status alone does not say. Two answers arrive under it that are about
* the model or the allowance, and both must keep advancing the routing chain
* exactly as they did before the subscription stop existed:
*
* - a model the provider does not carry. OpenCode Zen Go answers
* `401 "Model deepseek-v4-pro-0813 is not supported"` (measured 2026-08-18,
* the same key serving `kimi-k3` with 200) and
* `401 "Model grok-4.6 is not supported for format oa-compat"`
* (ai-docs/reports/grok-46-zen-go-misroute-was-stale-902-20260907.md). A
* catalog that drifts behind the plan sends such a model there, and the
* next hop serves it. Read with `hasModelUnsupportedWording`, the one
* predicate the recovery hint and the probe state already share;
* - a spent allowance (`403 "You've reached your usage limit for this
* billing cycle"`, Kimi Code), read with `isQuotaExhaustionError`, which
* advances with its per-token warning;
* - a model the account may not use HERE. Zen Go answers
* `403 {"error":{"type":"RegionError","message":"The latest version of this
* model is only available hosted in China and requires explicit opt in: …"}}`
* (measured 2026-08-19, `model-unsupported.ts`). Read from the provider's
* own error TYPE, which names a region rather than a credential.
*
* Only what is left is a credential verdict: the terminal 400 that stops an
* explicit spec, and that a routing chain announces as it moves to the next hop.
*/
export function isCredentialRejection(status: number, errorBody: string): boolean {
if (status !== 401 && status !== 403) return false;
if (hasModelUnsupportedWording(errorBody)) return false;
if (isQuotaExhaustionError(status, errorBody)) return false;
if (/region/i.test(providerErrorType(errorBody) ?? "")) return false;
return true;
}
/**
* The provider's own `error.type` in a raw upstream JSON error body. Read at
* the sites that hold the upstream body (the generic remap, settleAuthRetry);
* claudish's remapped 400 does not carry it. FallbackHandler's own
* subscription rule therefore treats a RAW 403 as a rejection (whose body still
* carries the type, so a 403 RegionError is a per-model miss) and not a recovered one.
*/
function providerErrorType(errorBody: string): string | undefined {
try {
const type = (JSON.parse(errorBody) as { error?: { type?: unknown } })?.error?.type;
return typeof type === "string" ? type : undefined;
} catch {
return undefined;
}
}
/** The fields a credential path sets on what it throws. */
interface ErrorFields {
message?: unknown;
terminal?: unknown;
transient?: unknown;
upstreamStatus?: unknown;
}
/** The status a transient failure carries, from the fields a credential path sets. */
function transientStatus(e: ErrorFields | undefined): number | undefined {
const status = typeof e?.upstreamStatus === "number" ? e.upstreamStatus : undefined;
if (status === 429 || (status !== undefined && status >= 500 && status <= 599)) return status;
if (e?.transient === true) return status ?? 503;
return undefined;
}
/**
* Classify a failure thrown at a credential site. ONE place, in one order:
* connection → terminal → transient → unknown.
*
* Reads only fields a credential path sets on purpose: `classifyConnectionError`
* for a network fault, `terminal: true`, `upstreamStatus` (429 or 5xx) or
* `transient: true`. The message is never parsed.
*/
export function classifyAuthFailure(err: unknown): AuthFailure {
const conn = classifyConnectionError(err);
if (conn) return { kind: "connection", conn };
const e = err as ErrorFields | undefined;
const message = typeof e?.message === "string" && e.message ? e.message : String(err);
if (e?.terminal === true) {
const upstreamStatus = typeof e.upstreamStatus === "number" ? e.upstreamStatus : undefined;
return {
kind: "terminal",
message,
...(upstreamStatus !== undefined ? { upstreamStatus } : {}),
};
}
const status = transientStatus(e);
if (status !== undefined) return { kind: "transient", status, message };
return { kind: "unknown", message };
}
/**
* Answer a classified credential failure. Never called for `connection`: the
* caller recovers those first (and gets `null` back if it does not).
*
* - terminal → 400 `invalid_request_error`, verdict `terminal`. `upstream_status`
* is kept for probes.
* - transient → 429 for a 429, 503 for any 5xx, verdict `transient`: Claude
* Code's own retry re-sends to the same hop. Never 401.
* - unknown on a subscription → as transient: 503 and the transient verdict (see
* the module comment).
* - unknown on a metered provider → 401 `authentication_error`, unchanged from
* before, so the chain may try a provider holding another credential. Only
* the two sites that already answered 401 (refreshAuth, forceRefreshAuth)
* may ask for this; every other site rethrows an unknown metered failure
* unchanged rather than invent a status.
*
* Every body goes to Claude Code, so the message passes through
* `redactForClient` before it is interpolated: a refresh exception or an auth
* host's error can quote the credential the rejected attempt signed with.
* Only the message changes; the kind, status and verdict header do not.
*/
export function respondAuthFailure(
c: Context,
classified: AuthFailure,
opts: { isSubscription: boolean; providerDisplayName: string }
): Response | null {
const failure: AuthFailure =
classified.kind === "connection"
? classified
: { ...classified, message: redactForClient(classified.message) };
switch (failure.kind) {
case "connection":
return null;
case "terminal":
return terminalResponse(c, failure.message, failure.upstreamStatus);
case "transient": {
const status = failure.status === 429 ? 429 : 503;
return c.json(
wrapAnthropicError(
status,
`${opts.providerDisplayName} could not confirm the credential (HTTP ${failure.status}): ${failure.message}`,
status === 429 ? "rate_limit_error" : "overloaded_error",
failure.status
),
status as ContentfulStatusCode,
authVerdictHeaders("transient")
);
}
case "unknown":
if (opts.isSubscription) {
return c.json(
wrapAnthropicError(
503,
`${opts.providerDisplayName} could not confirm the credential: ${failure.message}`,
"overloaded_error"
),
503,
authVerdictHeaders("transient")
);
}
return c.json(wrapAnthropicError(401, failure.message, "authentication_error"), 401);
}
}
function terminalResponse(c: Context, message: string, upstreamStatus?: number): Response {
return c.json(
wrapAnthropicError(400, message, "invalid_request_error", upstreamStatus),
400,
authVerdictHeaders("terminal")
);
}