@@ -37,6 +37,7 @@ import {
 import { getConfiguredSentryUrl } from "../constants.js";
 import { getEnv } from "../env.js";
 import {
+  type ApiDenialReason,
   ApiError,
   CliError,
   type FunctionArgument,
@@ -53,6 +54,12 @@ import {
 import { getSdkClientConfig } from "../sentry-sdk-client.js";
 import { isSentrySaasUrl } from "../sentry-urls.js";
 
+/** User-facing detail for a 401/403, and the reason to record for it. */
+type EnrichedDetail = {
+  detail: string;
+  denialReason: ApiDenialReason;
+};
+
 /**
  * Enrich a 403 Forbidden error detail with actionable guidance.
  *
@@ -66,15 +73,18 @@ import { isSentrySaasUrl } from "../sentry-urls.js";
  * - env-var tokens → suggest checking token scopes
  * - OAuth tokens → suggest re-authentication
  */
-function enrich403Detail(rawDetail: string | undefined): string {
+function enrich403Detail(rawDetail: string | undefined): EnrichedDetail {
   // Org-level policy — re-auth and token scope advice do not apply here.
   if (rawDetail?.includes("disabled this feature")) {
-    return [
-      rawDetail,
-      "",
-      "This is an org-level policy setting, not an auth issue.",
-      "You need org:admin/manager/owner role, or team:admin role on the team.",
-    ].join("\n  ");
+    return {
+      detail: [
+        rawDetail,
+        "",
+        "This is an org-level policy setting, not an auth issue.",
+        "You need org:admin/manager/owner role, or team:admin role on the team.",
+      ].join("\n  "),
+      denialReason: "member_policy",
+    };
   }
 
   const lines: string[] = [];
@@ -109,7 +119,10 @@ function enrich403Detail(rawDetail: string | undefined): string {
       `Re-authenticate with: ${sentry`auth login`}`,
     );
   }
-  return lines.join("\n  ");
+  return {
+    detail: lines.join("\n  "),
+    denialReason: scopes.length > 0 ? "insufficient_scope" : "access_denied",
+  };
 }
 
 /**
@@ -131,25 +144,28 @@ function enrich403Detail(rawDetail: string | undefined): string {
  *
  * @see https://github.com/getsentry/sentry/blob/934f1473f198a62f9268d7140b80cd9ca1e59bb9/src/sentry/api/authentication.py#L536-L539
  */
-function enrich401Detail(rawDetail: string | undefined): string {
+function enrich401Detail(rawDetail: string | undefined): EnrichedDetail {
   // 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`issue list my-other-org/`}`,
-    ].join("\n  ");
+    return {
+      detail: [
+        "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`issue list my-other-org/`}`,
+      ].join("\n  "),
+      denialReason: "seat_limit",
+    };
   }
 
   const lines: string[] = [];
   if (rawDetail) {
     lines.push(rawDetail, "");
   }
+  const expired = rawDetail?.toLowerCase().includes("expired") ?? false;
   if (isEnvTokenActive()) {
-    const expired = rawDetail?.toLowerCase().includes("expired");
     lines.push(
       `Your ${getActiveEnvVarName()} token ${expired ? "has expired" : "is not recognized or has been revoked"}.`,
       "Create a new token at: https://sentry.io/settings/account/api/auth-tokens/",
@@ -160,15 +176,19 @@ function enrich401Detail(rawDetail: string | undefined): string {
       `Re-authenticate with: ${sentry`auth login`}`,
     );
   }
-  return lines.join("\n  ");
+  return {
+    detail: lines.join("\n  "),
+    denialReason: expired ? "expired" : "unrecognized",
+  };
 }
 
 /**
  * Select and apply status-specific detail enrichment.
  *
  * Extracted from {@link throwApiError} and {@link throwRawApiError} to keep
  * their cognitive complexity within the linter limit. 403 and 401 get
- * actionable guidance; all other statuses pass the raw detail through.
+ * actionable guidance and a {@link ApiDenialReason}; all other statuses pass
+ * the raw detail through.
  *
  * `hasUsableDetail` controls whether the raw detail string is forwarded to
  * the enrichment functions — passing `undefined` when false lets them render
@@ -178,14 +198,14 @@ function enrichDetail(
   status: number,
   detail: string | undefined,
   hasUsableDetail: boolean,
-): string | undefined {
+): { detail: string | undefined; denialReason?: ApiDenialReason } {
   if (status === 403) {
     return enrich403Detail(hasUsableDetail ? detail : undefined);
   }
   if (status === 401) {
     return enrich401Detail(hasUsableDetail ? detail : undefined);
   }
-  return detail;
+  return { detail };
 }
 
 /**
@@ -377,13 +397,17 @@ export function throwApiError(
     ? stringifyUnknown(rawDetail)
     : stringifyUnknown(error);
 
-  const is403 = status === 403;
+  const enriched = enrichDetail(status, detail, hasUsableDetail);
   throw new ApiError(
     `${context}: ${status} ${response.statusText ?? "Unknown"}`,
     status,
-    enrichDetail(status, detail, hasUsableDetail),
+    enriched.detail,
     undefined,
-    { enriched403: is403, ...readErrorFields(error) },
+    {
+      enriched403: status === 403,
+      denialReason: enriched.denialReason,
+      ...readErrorFields(error),
+    },
   );
 }
 
@@ -918,13 +942,17 @@ export async function throwRawApiError(
     "x-sentry-error": response.headers.get("x-sentry-error"),
     "www-authenticate": response.headers.get("www-authenticate"),
   });
-  const is403 = response.status === 403;
+  const enriched = enrichDetail(response.status, detail, detail !== undefined);
   throw new ApiError(
     `${context}: ${response.status} ${response.statusText}`,
     response.status,
-    enrichDetail(response.status, detail, detail !== undefined),
+    enriched.detail,
     endpoint,
-    { enriched403: is403, ...readErrorFields(body.json) },
+    {
+      enriched403: response.status === 403,
+      denialReason: enriched.denialReason,
+      ...readErrorFields(body.json),
+    },
   );
 }
 
 
@@ -215,6 +215,9 @@ function recordSilencedError(error: unknown, reason: SilenceReason): void {
   };
   if (error instanceof ApiError) {
     attributes.api_status = error.status;
+    if (error.denialReason) {
+      attributes.api_denial_reason = error.denialReason;
+    }
   }
   if (error instanceof AuthError) {
     attributes.auth_reason = error.reason;
@@ -234,14 +237,17 @@ function recordSilencedError(error: unknown, reason: SilenceReason): void {
   }
 
   // Structured log for user API errors — `detail` is often the most actionable
-  // field and is searchable in Sentry Logs.
+  // field and is searchable in Sentry Logs. A 401/403 logs its denial reason
+  // instead: its detail is the CLI's own guidance, not the server's.
   if (reason === "api_user_error" && error instanceof ApiError) {
     // oxlint-disable-next-line sentry-cli/no-silent-catch -- grandfathered silent catch — see #1531; drain by adding log.debug()/log.warn() or re-throwing.
     try {
       Sentry.logger.info("cli.api_error_silenced", {
         status: error.status,
         endpoint: error.endpoint,
-        detail: error.detail,
+        ...(error.denialReason
+          ? { denial_reason: error.denialReason }
+          : { detail: error.detail }),
       });
     } catch {
       // Logger may not be initialized — ignore.
 
@@ -170,6 +170,30 @@ export type FunctionArgument = {
   hint?: string;
 };
 
+/**
+ * Why Sentry refused a request with a 401 or 403, as far as the CLI can tell.
+ *
+ * Recorded on spans and the `cli.error.silenced` metric, so each value is a
+ * fixed category: never a slug, token, URL, or text from the server. Avoid
+ * words such as "auth" and "token" in new values; Sentry's data scrubbing
+ * replaces values that contain them with `[Filtered]`.
+ *
+ * - `insufficient_scope`: the token lacks every scope the endpoint accepts
+ * - `member_policy`: an org setting blocks members from the action
+ * - `seat_limit`: the member is disabled because the org is over its limit
+ * - `access_denied`: a 403 that names no missing scope
+ * - `expired`: Sentry says the credential expired
+ * - `unrecognized`: Sentry does not know the credential (revoked, mistyped,
+ *   or created on another server)
+ */
+export type ApiDenialReason =
+  | "insufficient_scope"
+  | "member_policy"
+  | "seat_limit"
+  | "access_denied"
+  | "expired"
+  | "unrecognized";
+
 /**
  * API request errors from Sentry.
  *
@@ -204,6 +228,9 @@ export class ApiError extends CliError {
    */
   readonly enriched403: boolean;
 
+  /** Set with the 401/403 enrichment in `infrastructure.ts`. */
+  readonly denialReason?: ApiDenialReason;
+
   constructor(
     message: string,
     status: number,
@@ -213,10 +240,12 @@ export class ApiError extends CliError {
       enriched403 = false,
       code,
       functionArgument,
+      denialReason,
     }: {
       enriched403?: boolean;
       code?: string;
       functionArgument?: FunctionArgument;
+      denialReason?: ApiDenialReason;
     } = {},
   ) {
     super(message, EXIT.API);
@@ -227,6 +256,7 @@ export class ApiError extends CliError {
     this.enriched403 = enriched403;
     this.code = code;
     this.functionArgument = functionArgument;
+    this.denialReason = denialReason;
   }
 
   override format(): string {
 
@@ -436,15 +436,22 @@ export function isUserApiError(error: unknown): boolean {
 /**
  * Record a client API error as span attributes for Discover queryability.
  *
- * Sets `api_error.status`, `api_error.message`, and optionally `api_error.detail`
- * on the span. Must be called before `span.end()`.
+ * Sets `api_error.status`, `api_error.message`, and either
+ * `api_error.denial_reason` (401/403) or `api_error.detail` on the span. Must
+ * be called before `span.end()`.
+ *
+ * A 401/403 detail is the CLI's own guidance rather than the server's, and
+ * Sentry's data scrubbing replaces most of them with `[Filtered]`. The denial
+ * reason is a fixed category that tells those failures apart instead.
  *
  * @internal Exported for testing
  */
 export function recordApiErrorOnSpan(span: Span, error: ApiError): void {
   span.setAttribute("api_error.status", error.status);
   span.setAttribute("api_error.message", error.message);
-  if (error.detail) {
+  if (error.denialReason) {
+    span.setAttribute("api_error.denial_reason", error.denialReason);
+  } else if (error.detail) {
     span.setAttribute("api_error.detail", error.detail);
   }
 }