fix(init): show actionable error when org is over its member limit

When the target org is over its member limit, Sentry disables the
caller's seat and returns 401 `member-disabled-over-limit` for
region-scoped calls like listing teams. `sentry init` resolved the org
fine from the control-plane org list, then hit this 401 during team
resolution and surfaced a bare "Failed to list teams / 401" — and the
generic 401 path told the user to re-authenticate, which can't fix a
seat-limit lockout.

Recognize the code in enrich401Detail and explain the real cause (org
over member limit, ask an owner to upgrade/free a seat, or use another
org). Preserve the enriched detail through the init team-resolution
paths (implicit and explicit) and resolve-team's 401 handling so the
guidance reaches the user instead of being flattened.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: betegon

src/lib/api/infrastructure.ts

@@ -102,6 +102,18 @@ function enrich403Detail(rawDetail: string | undefined): string {
  * @see https://github.com/getsentry/sentry/blob/934f1473f198a62f9268d7140b80cd9ca1e59bb9/src/sentry/api/authentication.py#L536-L539
  */
 export function enrich401Detail(rawDetail: string | undefined): string {
+  // Seat-limit lockout, not an auth failure. Sentry returns 401 with
+  // `code: member-disabled-over-limit` when the org is over its member limit
+  // and the caller's seat is disabled — re-authenticating cannot fix this.
+  if (rawDetail?.includes("member-disabled-over-limit")) {
+    return [
+      "Your account is disabled in this organization because it is over its member limit.",
+      "This is a billing/seat-limit issue, not an auth problem — re-authenticating won't help.",
+      "Ask an org owner to upgrade the plan or free up a seat, then retry.",
+      "Or target a different org, e.g.:  sentry init my-other-org/",
+    ].join("\n  ");
+  }
+
   const lines: string[] = [];
   if (rawDetail) {
     lines.push(rawDetail, "");

src/lib/init/preflight.ts

@@ -310,6 +310,23 @@ async function resolveExistingProjectChoice(opts: {
   };
 }
 
+/**
+ * Normalize a team-resolution failure into a WizardError, preserving an
+ * ApiError's enriched detail (e.g. 401 `member-disabled-over-limit`) via
+ * format() instead of collapsing to its bare message + status line.
+ */
+function toPreflightWizardError(error: unknown): WizardError {
+  if (error instanceof WizardError) {
+    return error;
+  }
+  if (error instanceof ApiError) {
+    return new WizardError(error.format());
+  }
+  return new WizardError(
+    error instanceof Error ? error.message : String(error)
+  );
+}
+
 async function resolveTeam(
   org: string,
   initial: WizardOptions,
@@ -334,9 +351,7 @@ async function resolveTeam(
     if (error instanceof ApiError && error.status === 403) {
       return;
     }
-    throw error instanceof WizardError
-      ? error
-      : new WizardError(error instanceof Error ? error.message : String(error));
+    throw toPreflightWizardError(error);
   }
 }
 
@@ -381,9 +396,7 @@ async function listTeamsForImplicitInit(
     if (error instanceof ApiError && error.status === 404) {
       return await buildOrgNotFoundError(org, "sentry init");
     }
-    throw error instanceof WizardError
-      ? error
-      : new WizardError(error instanceof Error ? error.message : String(error));
+    throw toPreflightWizardError(error);
   }
 }
 

src/lib/resolve-team.ts

@@ -119,6 +119,8 @@ export type ResolvedTeam = ResolvedConcreteTeam | DeferredResolvedTeam;
  * - 403 → member lacks team:read; re-thrown as `ApiError` so callers that
  *   implement a member-accessible fallback can detect it and use
  *   POST /organizations/{org}/projects/ instead.
+ * - 401 → re-thrown as `ApiError` so the enriched detail (expired session,
+ *   member-disabled-over-limit, etc.) survives instead of being flattened.
  * - other → generic ResolutionError (5xx, network, etc.)
  */
 async function handleListTeamsError(
@@ -137,6 +139,9 @@ async function handleListTeamsError(
     if (error.status === 403) {
       throw error;
     }
+    if (error.status === 401) {
+      throw error;
+    }
     throw new ResolutionError(
       `Organization '${orgSlug}'`,
       `could not be accessed (${error.status})`,

test/lib/api/infrastructure.test.ts

@@ -445,6 +445,39 @@ describe("throwApiError", () => {
       }
     });
 
+    test("treats member-disabled-over-limit as a seat-limit issue, not auth", () => {
+      const mockResponse = new Response("", {
+        status: 401,
+        statusText: "Unauthorized",
+      });
+
+      let captured: ApiError | undefined;
+      try {
+        throwApiError(
+          {
+            detail: {
+              code: "member-disabled-over-limit",
+              message: "Organization over member limit",
+              extra: { next: "/organizations/chisme/disabled-member/" },
+            },
+          },
+          mockResponse,
+          "Failed to list teams"
+        );
+      } catch (error) {
+        captured = error as ApiError;
+      }
+
+      expect(captured).toBeDefined();
+      expect(captured?.status).toBe(401);
+      expect(captured?.detail).toContain("over its member limit");
+      expect(captured?.detail).toContain("billing/seat-limit");
+      // The fix must NOT give the misleading re-auth advice for this case.
+      expect(captured?.detail).not.toContain("sentry auth login");
+      expect(captured?.detail).not.toContain("session has expired");
+      expect(captured?.detail).not.toContain("SENTRY_AUTH_TOKEN");
+    });
+
     describe("with OAuth token (no env var)", () => {
       let savedAuthToken: string | undefined;
       let savedToken: string | undefined;

test/lib/init/preflight.test.ts

@@ -583,6 +583,27 @@ describe("resolveInitContext", () => {
     expect(errorCall?.message).toContain("beta");
   });
 
+  test("surfaces the enriched detail when implicit listTeams returns 401", async () => {
+    // member-disabled-over-limit: a 401 from listTeams must reach the user with
+    // its actionable detail, not a bare "Failed to list teams" + status line.
+    listTeamsSpy.mockRejectedValueOnce(
+      new ApiError(
+        "Failed to list teams",
+        401,
+        "Your account is disabled in this organization because it is over its member limit."
+      )
+    );
+
+    const { ui, calls } = createMockUI();
+    await expect(resolveInitContext(makeOptions(), ui)).rejects.toThrow();
+
+    const errorCall = calls.find(
+      (c): c is Extract<MockCall, { kind: "log.error" }> =>
+        c.kind === "log.error"
+    );
+    expect(errorCall?.message).toContain("over its member limit");
+  });
+
   test("fails early when listTeams is forbidden and member project creation is disabled", async () => {
     listTeamsSpy.mockRejectedValueOnce(
       new ApiError("Forbidden", 403, "No team:read access")