fix: stop retrying LLM payment errors

src/cli/main.ts

@@ -2,6 +2,7 @@ import { parseCLIArguments } from "./args.js";
 import { runConvertCommand } from "./convert.js";
 import { runStatusCommand } from "./status.js";
 import { runSdpubCommand } from "./sdpub.js";
+import { LLMPaymentRequiredError } from "../llm/index.js";
 import { formatError } from "../utils/node-error.js";
 
 export async function main(): Promise<void> {
@@ -29,7 +30,15 @@ export async function main(): Promise<void> {
         return;
     }
   } catch (error) {
-    process.stderr.write(`${formatError(error)}\n`);
+    process.stderr.write(`${formatCLIError(error)}\n`);
     process.exitCode = 1;
   }
 }
+
+function formatCLIError(error: unknown): string {
+  if (error instanceof LLMPaymentRequiredError) {
+    return "LLM payment required. Check your provider billing status or account balance.";
+  }
+
+  return formatError(error);
+}

src/index.ts

@@ -1,4 +1,5 @@
 export { Language } from "./common/language.js";
+export { LLMPaymentRequiredError } from "./llm/index.js";
 export {
   type DigestProgressEvent,
   type SerialDiscoveryItem,

src/llm/client.ts

@@ -19,6 +19,7 @@ import { createHash } from "../utils/hash.js";
 import { formatError } from "../utils/node-error.js";
 import { LLMCache } from "./cache.js";
 import { LLMContext, type LLMContextRequestInput } from "./context.js";
+import { LLMPaymentRequiredError } from "./errors.js";
 import { createRequestLog } from "./request-log.js";
 import { getScopeDefaults, resolveSamplingSetting } from "./sampling.js";
 import type {
@@ -312,6 +313,17 @@ export class LLM<S extends string> {
       } catch (error) {
         lastError = error;
 
+        if (isPaymentRequiredError(error)) {
+          const paymentError = new LLMPaymentRequiredError(undefined, {
+            cause: error,
+          });
+
+          await requestLog.append(
+            `[[Error]]:\n${formatError(paymentError)}\n\n`,
+          );
+          throw paymentError;
+        }
+
         if (!isRetryableError(error)) {
           await requestLog.append(`[[Error]]:\n${formatError(error)}\n\n`);
           throw error;
@@ -526,6 +538,10 @@ function capitalize(value: string): string {
 
 function isRetryableError(error: unknown): boolean {
   if (APICallError.isInstance(error)) {
+    if (isPaymentRequiredError(error)) {
+      return false;
+    }
+
     if (error.isRetryable) {
       return true;
     }
@@ -536,6 +552,10 @@ function isRetryableError(error: unknown): boolean {
   return !isAbortLikeError(error) && isRetryableTransportError(error);
 }
 
+function isPaymentRequiredError(error: unknown): boolean {
+  return APICallError.isInstance(error) && error.statusCode === 402;
+}
+
 function isRetryableStatusCode(statusCode: number | undefined): boolean {
   return (
     typeof statusCode === "number" &&

src/llm/errors.ts

@@ -0,0 +1,12 @@
+export class LLMPaymentRequiredError extends Error {
+  public readonly isRetryable = false;
+  public readonly statusCode = 402;
+
+  public constructor(
+    message = "LLM payment required.",
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "LLMPaymentRequiredError";
+  }
+}

src/llm/index.ts

@@ -1,5 +1,6 @@
 export { LLM } from "./client.js";
 export { LLMContext } from "./context.js";
+export { LLMPaymentRequiredError } from "./errors.js";
 export {
   getScopeDefaults,
   resolveSamplingSetting,

test/cli/main.test.ts

@@ -66,6 +66,7 @@ vi.mock("../../src/cli/sdpub.js", () => ({
 }));
 
 import { main } from "../../src/cli/main.js";
+import { LLMPaymentRequiredError } from "../../src/llm/index.js";
 
 describe("cli/main", () => {
   const originalExitCode = process.exitCode;
@@ -284,4 +285,25 @@ describe("cli/main", () => {
     expect(stderrChunks).toStrictEqual(["convert failed: tls reset\n"]);
     expect(process.exitCode).toBe(1);
   });
+
+  it("writes a stable payment required message for LLM billing failures", async () => {
+    mainMockState.argsResult = {
+      args: {
+        help: false,
+        verbose: false,
+      },
+      help: false,
+      kind: "convert",
+    };
+    mainMockState.runError = new LLMPaymentRequiredError("provider message", {
+      cause: new Error("raw provider error"),
+    });
+
+    await main();
+
+    expect(stderrChunks).toStrictEqual([
+      "LLM payment required. Check your provider billing status or account balance.\n",
+    ]);
+    expect(process.exitCode).toBe(1);
+  });
 });

test/llm/client.test.ts

@@ -80,6 +80,7 @@ vi.mock("ai", () => ({
 
 import { SpineDigestScope } from "../../src/common/llm-scope.js";
 import { LLM } from "../../src/llm/client.js";
+import { LLMPaymentRequiredError } from "../../src/llm/errors.js";
 import { withTempDir } from "../helpers/temp.js";
 
 const RETRYABLE_TRANSPORT_CODES = [
@@ -584,6 +585,53 @@ describe("llm/client", () => {
     expect(aiMockState.generateTextCalls).toHaveLength(1);
   });
 
+  it.each([false, true])(
+    "wraps HTTP 402 payment errors without retrying when isRetryable is %s",
+    async (isRetryable) => {
+      const { APICallError } = await import("ai");
+      const MockAPICallError = APICallError as unknown as {
+        new (
+          message: string,
+          options?: {
+            cause?: unknown;
+            isRetryable?: boolean;
+            statusCode?: number;
+          },
+        ): Error;
+      };
+
+      aiMockState.generateTextError = new MockAPICallError("Payment required", {
+        isRetryable,
+        statusCode: 402,
+      });
+
+      const llm = new LLM({
+        dataDirPath: process.cwd(),
+        model: {
+          modelId: "test-model",
+          provider: "test-provider",
+        } as never,
+        retryIntervalSeconds: 0,
+      });
+
+      const request = llm.request([
+        {
+          content: "hello",
+          role: "user",
+        },
+      ]);
+
+      await expect(request).rejects.toMatchObject({
+        cause: aiMockState.generateTextError,
+        isRetryable: false,
+        message: "LLM payment required.",
+        statusCode: 402,
+      });
+      await expect(request).rejects.toBeInstanceOf(LLMPaymentRequiredError);
+      expect(aiMockState.generateTextCalls).toHaveLength(1);
+    },
+  );
+
   it("retries terminated transport errors for streamText", async () => {
     aiMockState.streamTextError = new TypeError("terminated");