feat(cli): Tell users when Seer is out of credits (#2150)

`sentry issue explain` and `sentry issue plan` treat every 402 from the
autofix endpoint as "Seer requires a paid plan" and offer a free trial.
An org on token-based billing that runs out of Seer credits gets that
message too. A run that starts and then stops for credits reads as
"Analysis completed but no root causes found" or "Plan creation failed".

- A 402 with `code: "seer_out_of_credits"` (added in
getsentry/sentry#130284) now raises a new `out_of_credits` Seer error.
Any other 402, including `seer_out_of_quota` and the 402 with no code
that older Sentry versions send, keeps the current no-budget error.
- A run that ends with `failure_reason: "out_of_credits"` raises the
same error from both commands.
- The error has its own exit code, 43, and is left out of the free trial
prompt.

What the user sees:

```
Your organization is out of Seer credits.

Someone with billing access can adjust Seer spend and auto-reload in Sentry:
  https://my-org.sentry.io/settings/billing/overview/?product=seer
```

A failed run is still retried on the next invocation, so someone who
topped up recovers by running the command again.

The 402 comes from getsentry/sentry#130283 and getsentry/sentry#130284,
which have both merged. Sentry's credit checks are behind the
`organizations:seer-credit-checks` flag, so for an org without it the
CLI behaves as it does today. The MCP equivalent is #2031.

Fixes CW-3075

Author: jaydgoss

apps/cli-docs/src/content/docs/exit-codes.md

@@ -39,6 +39,7 @@ react to failure categories without parsing stderr.
 | 40 | Seer Not Enabled | Seer is not enabled for the organization |
 | 41 | Seer No Budget | Seer requires a paid plan |
 | 42 | AI Disabled | AI features disabled by organization admin |
+| 43 | Seer Out Of Credits | Organization is out of Seer credits |
 | 50 | Upgrade Error | CLI upgrade operation failed |
 | 51 | Device Flow Error | OAuth device authorization flow failed |
 | 60 | Output Error | Command produced output but the operation failed |

packages/cli/AGENTS.md

@@ -907,7 +907,7 @@ CliError (base, exitCode=1)
 ├── ResolutionError (exitCode=23 — value provided but not found)
 ├── ValidationError (exitCode=21 — input validation)
 ├── DeviceFlowError (exitCode=51 — OAuth flow)
-├── SeerError (exitCode=40–42 by reason — 'not_enabled' | 'no_budget' | 'ai_disabled')
+├── SeerError (exitCode=40–43 by reason — 'not_enabled' | 'no_budget' | 'ai_disabled' | 'out_of_credits')
 ├── TimeoutError (exitCode=31 — operation timed out)
 └── UpgradeError (exitCode=50 — upgrade failures)
 ```

packages/cli/src/commands/issue/explain.ts

@@ -74,7 +74,12 @@ async function analyzeIssue(
     return { issue: issueArg.text, org, issueId, rootCauses };
   } catch (error) {
     if (error instanceof ApiError) {
-      throw handleSeerApiError(error.status, error.detail, resolvedOrg);
+      throw handleSeerApiError(
+        error.status,
+        error.detail,
+        resolvedOrg,
+        error.code,
+      );
     }
     throw error;
   }

packages/cli/src/commands/issue/plan.ts

@@ -11,7 +11,7 @@ import { triggerSolutionPlanning } from "../../lib/api-client.js";
 import { sentry } from "../../lib/app-identity.js";
 import { issueSelectorHelp } from "../../lib/arg-parsing.js";
 import { buildCommand } from "../../lib/command.js";
-import { ApiError, CliError } from "../../lib/errors.js";
+import { ApiError, CliError, SeerError } from "../../lib/errors.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
 import {
   formatSolution,
@@ -323,6 +323,9 @@ export const planCommand = buildCommand({
       });
 
       if (finalState.status === "ERROR") {
+        if (finalState.failure_reason === "out_of_credits") {
+          throw new SeerError("out_of_credits", org);
+        }
         throw new Error(
           "Plan creation failed. Check the Sentry web UI for details.",
         );
@@ -342,7 +345,12 @@ export const planCommand = buildCommand({
       return yield new CommandOutput(buildPlanData(finalState));
     } catch (error) {
       if (error instanceof ApiError) {
-        throw handleSeerApiError(error.status, error.detail, resolvedOrg);
+        throw handleSeerApiError(
+          error.status,
+          error.detail,
+          resolvedOrg,
+          error.code,
+        );
       }
       throw error;
     }

packages/cli/src/commands/issue/utils.ts

@@ -36,6 +36,7 @@ import {
   type AuthGuardFailure,
   ContextError,
   ResolutionError,
+  SeerError,
   withAuthGuard,
 } from "../../lib/errors.js";
 import { getProgressMessage } from "../../lib/formatters/seer.js";
@@ -1086,6 +1087,7 @@ type EnsureRootCauseOptions = {
  *
  * @param options - Configuration options
  * @returns The completed autofix state with root causes
+ * @throws {SeerError} When the run stopped because the org ran out of Seer credits
  */
 export async function ensureRootCauseAnalysis(
   options: EnsureRootCauseOptions,
@@ -1126,6 +1128,10 @@ export async function ensureRootCauseAnalysis(
     });
   }
 
+  if (state.status === "ERROR" && state.failure_reason === "out_of_credits") {
+    throw new SeerError("out_of_credits", org);
+  }
+
   return state;
 }
 

packages/cli/src/lib/errors.ts

@@ -83,6 +83,8 @@ export const EXIT = {
   SEER_NO_BUDGET: 41,
   /** AI features disabled by org admin */
   SEER_AI_DISABLED: 42,
+  /** Organization is out of Seer credits */
+  SEER_OUT_OF_CREDITS: 43,
 
   // 50–59: Operations
   /** CLI upgrade failed */
@@ -757,7 +759,11 @@ export class UpgradeTransportError extends UpgradeError {
 
 // Seer Errors
 
-export type SeerErrorReason = "not_enabled" | "no_budget" | "ai_disabled";
+export type SeerErrorReason =
+  | "not_enabled"
+  | "no_budget"
+  | "ai_disabled"
+  | "out_of_credits";
 
 /**
  * Seer-specific errors with actionable suggestions.
@@ -774,11 +780,13 @@ export class SeerError extends CliError {
       not_enabled: "Seer is not enabled for this organization.",
       no_budget: "Seer requires a paid plan.",
       ai_disabled: "AI features are disabled for this organization.",
+      out_of_credits: "Your organization is out of Seer credits.",
     };
     const exitCodes: Record<SeerErrorReason, number> = {
       not_enabled: EXIT.SEER_NOT_ENABLED,
       no_budget: EXIT.SEER_NO_BUDGET,
       ai_disabled: EXIT.SEER_AI_DISABLED,
+      out_of_credits: EXIT.SEER_OUT_OF_CREDITS,
     };
     super(messages[reason], exitCodes[reason]);
     this.name = "SeerError";
@@ -803,6 +811,10 @@ export class SeerError extends CliError {
         no_budget: `To use Seer features, upgrade your plan:\n  ${buildBillingUrl(this.orgSlug, "seer")}${trialHint}`,
         // ai_disabled is an admin decision — don't suggest trial
         ai_disabled: `To enable AI features:\n  ${buildOrgSettingsUrl(this.orgSlug, "hideAiFeatures")}`,
+        // out_of_credits orgs already have Seer, so a trial is not the fix.
+        // Sentry doesn't say whether auto-reload is off or has run through its
+        // top-ups, so the advice covers both.
+        out_of_credits: `Someone with billing access can adjust Seer spend and auto-reload in Sentry:\n  ${buildBillingUrl(this.orgSlug, "seer")}`,
       };
       return `${this.message}\n\n${suggestions[this.reason]}`;
     }
@@ -814,6 +826,9 @@ export class SeerError extends CliError {
       // ai_disabled is an admin decision — don't suggest trial
       ai_disabled:
         "To enable AI features, check the 'Hide AI Features' setting in your organization settings.",
+      // out_of_credits orgs already have Seer, so a trial is not the fix
+      out_of_credits:
+        "Someone with billing access can adjust Seer spend and auto-reload in your organization's billing settings.",
     };
     return `${this.message}\n\n${fallbackSuggestions[this.reason]}`;
   }

packages/cli/src/lib/formatters/seer.ts

@@ -260,21 +260,33 @@ export function jsonTransformIssueExplain(
 
 // Error Messages
 
+/**
+ * `code` Sentry sends with a 402 when the organization is out of Seer credits.
+ * Any other 402 means no budget, including one with no code from a Sentry
+ * version that predates the codes.
+ */
+const OUT_OF_CREDITS_CODE = "seer_out_of_credits";
+
 /**
  * Create a SeerError from an API error status code and detail.
  *
  * @param status - HTTP status code
  * @param detail - Error detail from API
  * @param orgSlug - Organization slug for constructing settings URLs
+ * @param code - Machine-readable `code` from the error body
  * @returns SeerError if the status code indicates a Seer-specific error, null otherwise
  */
 export function createSeerError(
   status: number,
   detail?: string,
   orgSlug?: string,
+  code?: string,
 ): SeerError | null {
   if (status === 402) {
-    return new SeerError("no_budget", orgSlug);
+    return new SeerError(
+      code === OUT_OF_CREDITS_CODE ? "out_of_credits" : "no_budget",
+      orgSlug,
+    );
   }
   if (status === 403) {
     if (detail?.includes("not enabled")) {
@@ -301,14 +313,16 @@ export function createSeerError(
  * @param status - HTTP status code
  * @param detail - Error detail from API
  * @param orgSlug - Organization slug for constructing settings URLs
+ * @param code - Machine-readable `code` from the error body
  * @returns SeerError for Seer-specific errors, or ApiError for other API errors
  */
 export function handleSeerApiError(
   status: number,
   detail?: string,
   orgSlug?: string,
+  code?: string,
 ): Error {
-  const seerError = createSeerError(status, detail, orgSlug);
+  const seerError = createSeerError(status, detail, orgSlug, code);
   if (seerError) {
     return seerError;
   }

packages/cli/src/types/seer.ts

@@ -189,6 +189,11 @@ export const AutofixStateSchema = looseObject({
   /** Null for legacy runs predating this field. */
   sentry_run_id: optional(nullable(string())),
   status: string(),
+  /**
+   * Why a failed run stopped, e.g. `out_of_credits`. Null when the run didn't
+   * fail, and also when it failed for a reason Seer doesn't classify.
+   */
+  failure_reason: optional(nullable(string())),
   updated_at: optional(string()),
   request: optional(
     object({

packages/cli/test/commands/issue/explain.func.test.ts

@@ -20,7 +20,7 @@ vi.mock("../../../src/commands/issue/utils.js", async (importOriginal) => {
 import { explainCommand } from "../../../src/commands/issue/explain.js";
 // oxlint-disable-next-line sentry-cli/no-namespace-import -- needed for spyOn mocking
 import * as issueUtils from "../../../src/commands/issue/utils.js";
-import { ContextError } from "../../../src/lib/errors.js";
+import { ApiError, ContextError } from "../../../src/lib/errors.js";
 import type { IssueArgument } from "../../../src/lib/issue-arguments.js";
 import type { AutofixState, RootCause } from "../../../src/types/seer.js";
 
@@ -172,6 +172,24 @@ describe("issue explain multiple IDs", () => {
     ).rejects.toBe(error);
   });
 
+  test("throws out_of_credits when Sentry refuses the analysis with a 402", async () => {
+    resolveSpy.mockResolvedValue({ org: "test-org", issueId: "1" });
+    analyzeSpy.mockRejectedValue(
+      new ApiError(
+        "Failed to start root cause analysis: 402 Payment Required",
+        402,
+        "Your organization does not have enough credits to start an Autofix run.",
+        undefined,
+        { code: "seer_out_of_credits" },
+      ),
+    );
+
+    const func = await explainCommand.loader();
+    await expect(
+      func.call(createMockContext().context, EXPLAIN_FLAGS, "IOS-1"),
+    ).rejects.toMatchObject({ reason: "out_of_credits", orgSlug: "test-org" });
+  });
+
   test("fails to parse when no issue ID is provided", async () => {
     const func = await explainCommand.loader();
     await expect(

packages/cli/test/commands/issue/plan.func.test.ts

@@ -23,7 +23,7 @@ import { planCommand } from "../../../src/commands/issue/plan.js";
 // oxlint-disable-next-line sentry-cli/no-namespace-import -- needed for spyOn mocking
 import * as issueUtils from "../../../src/commands/issue/utils.js";
 import { triggerSolutionPlanning } from "../../../src/lib/api-client.js";
-import { CliError } from "../../../src/lib/errors.js";
+import { ApiError, CliError } from "../../../src/lib/errors.js";
 import { logger } from "../../../src/lib/logger.js";
 import { prompt } from "../../../src/lib/prompt.js";
 import type { AutofixState, RootCause } from "../../../src/types/seer.js";
@@ -191,6 +191,38 @@ describe("issue plan after solution planning", () => {
     );
   });
 
+  test("throws out_of_credits when planning stopped for credits", async () => {
+    pollSpy.mockResolvedValue({
+      status: "ERROR",
+      failure_reason: "out_of_credits",
+      run_id: 42,
+      steps: [],
+    });
+
+    await expect(runPlan(createMockContext())).rejects.toMatchObject({
+      reason: "out_of_credits",
+      orgSlug: "test-org",
+    });
+  });
+
+  test("throws out_of_credits when Sentry refuses planning with a 402", async () => {
+    vi.mocked(triggerSolutionPlanning).mockRejectedValueOnce(
+      new ApiError(
+        "Failed to start solution planning: 402 Payment Required",
+        402,
+        "Your organization does not have enough credits to continue your Autofix run.",
+        undefined,
+        { code: "seer_out_of_credits" },
+      ),
+    );
+
+    await expect(runPlan(createMockContext())).rejects.toMatchObject({
+      reason: "out_of_credits",
+      orgSlug: "test-org",
+    });
+    expect(pollSpy).not.toHaveBeenCalled();
+  });
+
   test("throws when planning ends in CANCELLED", async () => {
     pollSpy.mockResolvedValue({ status: "CANCELLED", run_id: 42, steps: [] });