fix: add actionable suggestions for 400 Bad Request on issue list (CLI-BM, CLI-7B) (#489)

## Problem

When `sentry issue list` gets a 400 Bad Request from the API, the error
shows the raw API detail but doesn't guide users on what to fix. This is
the most common API error class, affecting **93 users** across
[CLI-BM](https://sentry.sentry.io/issues/7315010148/) (55 users) and
[CLI-7B](https://sentry.sentry.io/issues/7277810245/) (38 users).

Common causes include:
- Invalid Sentry search query syntax (e.g., unparenthesized OR
operators)
- Default `--period 90d` exceeding plan data retention
- Project access issues

## Fix

Added a `build400Detail()` helper that enriches the 400 error detail
with context-aware suggestions based on the current command flags:

**When `--query` is provided:**
```
Failed to fetch issues from 1 project(s): Failed to list issues: 400 Bad Request
  Invalid search query: ...

  Suggestions:
    • Check your --query syntax (Sentry search reference: https://docs.sentry.io/concepts/search/)
    • Try a shorter time range: --period 14d or --period 24h
    • Verify you have access to the target project: sentry project list <org>/
```

**When using default period (no --query):**
```
Failed to fetch issues from 1 project(s): Failed to list issues: 400 Bad Request
  ...

  Suggestions:
    • Try a shorter time range: --period 14d or --period 24h
    • Verify you have access to the target project: sentry project list <org>/
```

## Design Decisions

- Suggestions are **appended after** the original API detail so the
specific error reason is shown first
- The query syntax suggestion only appears when `--query` is actually
used
- The period suggestion only appears when using the default 90d (users
who explicitly set a period likely don't need this hint)
- The `build400Detail` function is intentionally narrow-scoped to 400
errors to avoid cluttering other error types

Author: BYK

src/commands/issue/list.ts

@@ -892,6 +892,61 @@ type ResolvedTargetsOptions = {
   setContext: (orgs: string[], projects: string[]) => void;
 };
 
+/** Default --period value (used to detect user-implicit vs explicit). */
+const DEFAULT_PERIOD = "90d";
+
+/**
+ * Build an enriched error detail for 400 Bad Request responses.
+ *
+ * Appends actionable suggestions so users know what to try next. This is the
+ * most common class of API error in `issue list` (CLI-BM, CLI-7B) — the Sentry
+ * API rejects the request due to query syntax or parameter issues, but the raw
+ * "400 Bad Request" message alone doesn't guide the user to a fix.
+ *
+ * @param originalDetail - The API response detail (may be undefined)
+ * @param flags - Current command flags for context-aware hints
+ * @returns Enhanced detail string with suggestions
+ */
+function build400Detail(
+  originalDetail: string | undefined,
+  flags: Pick<ListFlags, "query" | "period">
+): string {
+  const lines: string[] = [];
+
+  if (originalDetail) {
+    lines.push(originalDetail);
+  }
+
+  const suggestions: string[] = [];
+
+  if (flags.query) {
+    suggestions.push(
+      "Check your --query syntax (Sentry search reference: https://docs.sentry.io/concepts/search/)"
+    );
+  }
+
+  if (!flags.period || flags.period === DEFAULT_PERIOD) {
+    suggestions.push("Try a shorter time range: --period 14d or --period 24h");
+  }
+
+  suggestions.push(
+    "Verify you have access to the target project: sentry project list <org>/"
+  );
+
+  // Only add the separator when there's a detail line preceding the suggestions
+  if (lines.length > 0) {
+    lines.push("");
+  }
+  lines.push("Suggestions:");
+  for (const s of suggestions) {
+    lines.push(`  • ${s}`);
+  }
+
+  // ApiError.format() prepends "\n  " only before the first line of detail.
+  // Indent continuation lines to maintain alignment with the first line.
+  return lines.join("\n  ");
+}
+
 /**
  * Handle auto-detect, explicit, and project-search modes.
  *
@@ -1039,12 +1094,19 @@ async function handleResolvedTargets(
     const { error: first } = failures[0]!;
     const prefix = `Failed to fetch issues from ${targets.length} project(s)`;
 
-    // Propagate ApiError so telemetry sees the original status code
+    // Propagate ApiError so telemetry sees the original status code.
+    // For 400 errors, append actionable suggestions since the user's query
+    // or parameters are likely malformed. Common causes: invalid Sentry
+    // search syntax, unsupported period for the org's data retention.
     if (first instanceof ApiError) {
+      const detail =
+        first.status === 400
+          ? build400Detail(first.detail, flags)
+          : first.detail;
       throw new ApiError(
         `${prefix}: ${first.message}`,
         first.status,
-        first.detail,
+        detail,
         first.endpoint
       );
     }