Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* Anthropic error envelope wrapper.
* All proxy error responses MUST use this format.
*/
import { isContextOverflowError } from "./request-shape.js";
export type AnthropicErrorType =
| "invalid_request_error"
| "authentication_error"
| "permission_error"
| "not_found_error"
| "rate_limit_error"
| "overloaded_error"
| "api_error"
| "connection_error";
export interface AnthropicErrorEnvelope {
type: "error";
error: {
type: AnthropicErrorType;
message: string;
/**
* Original upstream HTTP status, set when the proxy REMAPS a terminal
* upstream error (401/403/terminal-429) to 400 so Claude Code surfaces it
* instead of silently retrying. Machine-readable: probe classification
* reads it to report the real upstream failure (e.g. "auth failed · 401")
* instead of the proxy's 400. Extra JSON fields are ignored by Claude Code.
*/
upstream_status?: number;
/**
* The UPSTREAM'S OWN WORDS, unedited — no hint, no provider name, no status.
*
* `message` is a composed sentence: claudish's recovery hint first, then the
* provider's text after an em dash. That order is right for Claude Code,
* which shows one line and needs the advice in it, and wrong for anything
* that has to fit the failure into a column. The probe row clips, so it was
* showing 100% of claudish's guess and 0% of the provider's fact — Alibaba
* said "Model access denied." and the row said "The provider accepted the
* credential but denied access to this model — check model access or…".
*
* A guess displacing the evidence is the wrong trade at any width, so the
* evidence travels separately and the probe leads with it. Same precedent as
* `upstream_status`: machine-readable, and extra JSON fields are ignored by
* Claude Code.
*/
provider_message?: string;
};
}
/**
* Map HTTP status codes to Anthropic error types.
*/
export function statusToErrorType(status: number): AnthropicErrorType {
switch (status) {
case 400:
return "invalid_request_error";
case 401:
return "authentication_error";
case 403:
return "permission_error";
case 404:
return "not_found_error";
case 429:
return "rate_limit_error";
case 503:
case 529:
return "overloaded_error";
default:
return "api_error";
}
}
/** Hard cap on an error message. Long enough to stay actionable, short enough
* that a client rendering it inline can't be pushed off-screen. */
const MAX_ERROR_MESSAGE_LENGTH = 600;
// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control chars is the point
const ANSI_ESCAPE = /\x1B\[[0-?]*[ -/]*[@-~]|\x1B[@-Z\\-_]/g;
// biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control chars is the point
const CONTROL_CHARS = /[\x00-\x1F\x7F]/g;
/**
* Flatten an error message into a single terminal-safe line.
*
* Claude Code renders a proxy error message INLINE in its "API error · Retrying"
* banner, inside a TUI frame it redraws in place. A message carrying newlines,
* tabs, or ANSI escapes therefore doesn't just look bad — it moves the cursor
* and overwrites whatever the TUI had already painted, which is how a raw Bun
* connect-error dump (`error: …` / `path: …` / `errno: …` / `code: …`) shredded
* the status line and surrounding rows.
*
* claudish does not control what a provider puts in an error body, so the fix
* has to live at the boundary: every message we emit is collapsed to one line,
* stripped of control bytes, and length-capped.
*/
export function sanitizeErrorMessage(
message: string,
maxLength = MAX_ERROR_MESSAGE_LENGTH
): string {
const flattened = String(message ?? "")
.replace(ANSI_ESCAPE, "") // cursor moves / colors — must go before control-char strip
.replace(CONTROL_CHARS, " ") // newlines, tabs, bells, backspaces → space
.replace(/\s+/g, " ")
.trim();
if (flattened.length <= maxLength) return flattened;
return `${flattened.slice(0, maxLength - 1).trimEnd()}…`;
}
/**
* Create a properly formatted Anthropic error envelope.
*
* The message is always sanitized (see sanitizeErrorMessage) — this is the one
* choke point every proxy error response passes through, so it is the only
* place that can guarantee a client-rendered error can't corrupt a TUI.
*
* @param status - HTTP status code (used to infer error type if not provided)
* @param message - Human-readable error message
* @param errorType - Override the error type (e.g., from a provider's structured error)
* @param upstreamStatus - Original upstream HTTP status when this envelope remaps
* a terminal error to a different status (see interface doc)
*/
export function wrapAnthropicError(
status: number,
message: string,
errorType?: string,
upstreamStatus?: number,
providerMessage?: string
): AnthropicErrorEnvelope {
const type = (errorType as AnthropicErrorType) || statusToErrorType(status);
const error: AnthropicErrorEnvelope["error"] = { type, message: sanitizeErrorMessage(message) };
if (upstreamStatus !== undefined) error.upstream_status = upstreamStatus;
// Flattened to one line here rather than at each caller: the field exists to
// be rendered in a single row, and a provider may answer with a multi-line SSE
// frame. Sanitised like `message`, because it is provider text either way.
const oneLine = (providerMessage ?? "").replace(/\s+/g, " ").trim();
if (oneLine) error.provider_message = sanitizeErrorMessage(oneLine);
return { type: "error", error };
}
/**
* Recover the ORIGINAL upstream status from a remapped error body.
*
* The remap (`composed-handler.ts`, the single site that passes a fourth
* argument to `wrapAnthropicError`) turns a terminal upstream failure into an
* HTTP 400 so Claude Code surfaces it inline instead of burying it under ten
* rounds of "API error · Retrying". That is right for the CLIENT and wrong for
* anything downstream that still has a decision to make from the status, so the
* true status rides along in this field.
*
* Two callers need it and they were not sharing one reader: `probe-live.ts`
* (which would otherwise bucket a remapped auth failure as a generic
* "error · 400") and `fallback-handler.ts` (#148 — which would otherwise stop a
* provider chain dead on an error that the very next candidate could serve).
* A private copy in each is how they drift.
*
* Returns `undefined` for a body that is not JSON, carries no field, or carries
* a non-numeric one. Never throws: it runs on the error path, where something
* has already gone wrong.
*/
export function extractUpstreamStatus(body: string): number | undefined {
if (!body) return undefined;
try {
const parsed = JSON.parse(body);
const status = parsed?.error?.upstream_status;
return typeof status === "number" ? status : undefined;
} catch {
return undefined;
}
}
/**
* The concatenated `data:` payload of an SSE frame, or undefined for anything
* else. Exported because the probe needs the same reading.
*
* A provider may answer an ERROR as a stream rather than a document — the
* request asked for `stream: true`, so some providers answer in kind. Alibaba
* Model Studio does exactly this for a denied model:
*
* event:error
* data:{"code":"AccessDenied","message":"Model access denied.","request_id":"…"}
*
* The whole frame is not JSON, so every JSON ladder below it fails and the frame
* survives verbatim into a user-facing sentence — three lines of wire protocol
* where "Model access denied." belonged. Multiple `data:` lines concatenate,
* per the SSE specification.
*/
export function sseDataPayload(body: string): string | undefined {
// Anchored to the START of the text. An SSE frame begins with its field name;
// an ordinary error sentence merely CONTAINS " data:", and the unanchored
// detector sliced such a sentence at that point: `"Missing key in request data:
// messages"` came back as `"messages"`, and `"Invalid content block: data: URLs
// are not supported"` lost everything before "URLs". That cut-down text is what
// Claude Code shows, so the reader got a fragment instead of the provider's
// sentence. Caught in release review for v10.0.2.
if (!/^\s*(event|data):/.test(body)) return undefined;
// Shape 1: a real frame, still carrying its line breaks. Multiple `data:`
// lines concatenate, per the specification.
const lines = body.split(/\r?\n/).filter((line) => line.startsWith("data:"));
if (lines.length > 0) {
const joined = lines.map((line) => line.slice("data:".length).trim()).join("");
if (joined.length > 0) return joined;
}
// Shape 2: the SAME frame after its newlines became spaces. `sanitizeErrorMessage`
// does that to every message the proxy returns — deliberately, so a provider
// cannot corrupt a client's terminal — and it runs BEFORE the probe reads the
// text. So the probe never sees shape 1 on a proxied error, only
// `event:error data:{…}` on one line, where no line starts with `data:` and
// shape 1 finds nothing. Everything after the first `data:` is the payload;
// a frame carrying several data fields has already lost its boundaries by
// this point, and one JSON object is the case that occurs.
const at = body.search(/(^|\s)data:/);
if (at === -1) return undefined;
const payload = body.slice(body.indexOf("data:", at) + "data:".length).trim();
return payload.length > 0 ? payload : undefined;
}
/**
* Pull the most useful human-readable message out of an arbitrary provider
* error body (already JSON-parsed, or a raw string). Mirrors the extraction
* ladder in ensureAnthropicErrorFormat but usable standalone.
*/
export function extractProviderMessage(body: any): string {
if (body == null) return "";
if (typeof body === "string") {
// A streamed error is still a document once the frame is opened. Only the
// payload is re-entered, so a frame that carries no recognisable message
// falls back to the frame itself rather than to nothing.
const payload = sseDataPayload(body);
if (payload) {
try {
const inner = extractProviderMessage(JSON.parse(payload));
if (inner) return inner;
} catch {
return payload;
}
return payload;
}
return body;
}
const candidates = [
body?.error?.message,
body?.message,
typeof body?.error === "string" ? body.error : undefined,
body?.error?.detail,
body?.detail,
];
for (const c of candidates) {
// Re-entered through the string arm, not returned directly: a message field
// can itself hold a whole SSE frame. claudish re-wraps a raw upstream body
// as `{error:{message: <that body>}}` on the auth-retry return, which is
// valid JSON, so this ladder succeeded and handed back wire protocol.
if (typeof c === "string" && c.length > 0) return extractProviderMessage(c);
// FastAPI validation errors use `detail: [{ msg, loc, ... }]`.
if (Array.isArray(c)) {
const first = c.find((e) => typeof e?.msg === "string" && e.msg.length > 0);
if (first) return first.msg;
}
}
try {
return JSON.stringify(body);
} catch {
return String(body);
}
}
/**
* Decide whether an upstream error is *terminal* — i.e. retrying will not help,
* so claudish should stop Claude Code's silent retry loop and surface the real
* reason inline. Generalizes the terminal-429 special case to any status that
* carries an auth / quota / billing / model-unsupported signal.
*
* Transient errors (plain rate limits, overloaded, 5xx blips) are NOT terminal:
* those legitimately recover on retry, so we leave the retryable status intact.
*
* Substring matching is deliberately CONSERVATIVE. A false positive here is
* worse than a false negative: classifying a transient error as terminal stops
* a retry that would have succeeded, whereas missing a terminal error only
* costs a few wasted retries before the final attempt surfaces the real reason.
* So:
* - Quota/billing phrases (`insufficient balance`, `out of credits`, …) are
* specific enough to trust under ANY status — no transient blip phrases it
* that way.
* - Generic English phrases (`not supported`, `subscription … expired`) are
* gated to non-5xx statuses, because a 5xx is a SERVER failure (retry-worthy)
* and such prose can legitimately appear inside a transient 5xx body
* (e.g. "Retry-After not supported by upstream gateway; service overloaded").
*
* @param status - upstream HTTP status
* @param bodyText - raw upstream error body (string)
* @param terminal429 - result of provider-specific isTerminal429(bodyText)
*/
export function isTerminalError(status: number, bodyText: string, terminal429: boolean): boolean {
// Auth / permission failures never recover on retry.
if (status === 401 || status === 403) return true;
// 426 Upgrade Required is terminal BY DEFINITION — RFC 7231: the server
// "refuses to perform the request using the current protocol but might be
// willing to after the client upgrades". Re-sending the identical request can
// never succeed, so a retry loop only buries the fix.
//
// Not hypothetical: Grok Build's proxy enforces a minimum CLI version and
// answers 426 with `Your Grok CLI version (X) is outdated. Please update ...
// via \`grok update\``. That body matches none of the phrase lists below, so
// it fell through as retryable and the one actionable sentence was replaced
// by ~11 rounds of "API error · Retrying".
if (status === 426) return true;
// Billing/quota exhaustion surfaced as a 429 (provider-specific signals).
if (status === 429 && terminal429) return true;
// A prompt larger than the model's context window is terminal BY ARITHMETIC:
// re-sending the identical request can only produce the identical rejection.
// Terminal here means the envelope is remapped to 400 and carries the rich
// surfaced message, which is the only path on which the client ever sees the
// `prompt is too long` phrase it pattern-matches — the plain pass-through
// forwards the provider's own wording, which no client recognises.
//
// It does NOT change the fallback chain: `fallback-handler` only widens on a
// recovered upstream 401/402/403/429, and an overflow is none of those.
if (isContextOverflowError(status, bodyText)) return true;
const lower = (bodyText || "").toLowerCase();
// Quota/billing signals: specific enough to trust under any status. A
// transient overload never describes itself as "insufficient balance".
if (
lower.includes("insufficient balance") ||
lower.includes("insufficient_balance") ||
lower.includes("insufficient_quota") ||
lower.includes("insufficient quota") ||
lower.includes("billing_not_active") ||
lower.includes("billing not active") ||
lower.includes("out of credits") ||
lower.includes("no credits remaining") ||
lower.includes("exceeded your current quota") ||
lower.includes("quota_exceeded")
) {
return true;
}
// Generic-English terminal phrases (model-unsupported, expired subscription).
// These appear in real prose, so gate them to non-5xx statuses: a 5xx is a
// server failure that should retry, and "not supported" can show up inside a
// transient gateway message. A model/account problem comes back as 4xx.
const isServerError = status >= 500;
if (!isServerError) {
if (
lower.includes("not supported") ||
lower.includes("unsupported model") ||
lower.includes("unsupported_model") ||
lower.includes("model not found") ||
lower.includes("model_not_found") ||
lower.includes("unknown model") ||
(lower.includes("subscription") && lower.includes("expired"))
) {
return true;
}
}
return false;
}
/**
* Build a single user-readable line that survives in the chat transcript when
* an upstream error is surfaced (instead of Claude Code's opaque
* "API error · Retrying"). Combines provider attribution, HTTP status, a
* recovery hint, and the real upstream message.
*
* Example:
* "Sakana Fugu error (HTTP 401): Check API key / OAuth credentials. — invalid api key"
*/
export function buildSurfacedErrorMessage(opts: {
providerDisplayName: string;
status: number;
hint: string;
providerMessage: string;
/**
* A phrase the CLIENT pattern-matches, placed at the very front of the line.
*
* It LEADS for two independent reasons, and either alone would be enough.
* `sanitizeErrorMessage` caps the message at 600 characters, so a phrase
* appended after provider prose can be cut off — and a client matching a
* truncated phrase misses silently. And Claude Code's own message classifier
* tests `startsWith("prompt is too long")`, not a substring, so the position
* is itself load-bearing.
*
* Only `CONTEXT_OVERFLOW_PHRASE` uses this today. See `request-shape.ts`.
*/
leadPhrase?: string;
}): string {
const { providerDisplayName, status, hint, providerMessage, leadPhrase } = opts;
const head = `${providerDisplayName} error (HTTP ${status})`;
const parts: string[] = [head];
if (hint) parts[0] = `${head}: ${hint}`;
if (leadPhrase && !parts[0].startsWith(leadPhrase)) parts[0] = `${leadPhrase} — ${parts[0]}`;
const detail = (providerMessage || "").trim();
if (detail && !parts[0].includes(detail)) {
// Keep the surfaced line bounded — providers occasionally echo huge bodies.
const trimmed = detail.length > 600 ? `${detail.slice(0, 600)}…` : detail;
parts.push(`— ${trimmed}`);
}
return parts.join(" ");
}
/**
* Check if a parsed JSON body is already in Anthropic error envelope format.
* Returns the body as-is if valid, or wraps it if not.
*/
export function ensureAnthropicErrorFormat(status: number, body: any): AnthropicErrorEnvelope {
// Already correct format: { type: "error", error: { type: "...", message: "..." } }
// Still sanitize the message: a well-formed envelope is no guarantee of a
// well-behaved message, and this pass-through is the one path where provider
// text reaches the client without claudish having composed it.
if (
body?.type === "error" &&
typeof body?.error?.type === "string" &&
typeof body?.error?.message === "string"
) {
return { ...body, error: { ...body.error, message: sanitizeErrorMessage(body.error.message) } };
}
// Partial format: { error: { type: "...", message: "..." } } (missing outer type)
if (typeof body?.error?.type === "string" && typeof body?.error?.message === "string") {
return {
type: "error",
error: { ...body.error, message: sanitizeErrorMessage(body.error.message) },
};
}
// Provider returned some other JSON structure -- extract best message
const message =
body?.error?.message ||
body?.message ||
body?.error ||
(typeof body === "string" ? body : JSON.stringify(body));
const errorType = body?.error?.type || body?.type || body?.code;
return wrapAnthropicError(status, String(message), errorType);
}