fix(uptime): Explain seat errors when enabling a monitor (#2120)

Enabling an uptime monitor fails with a field error when the
organization has no seat or pay-as-you-go budget.
`update_uptime_monitor` passed that error through as a raw JSON body,
and these failures are a large share of the tool's 400s. The tool now
returns the server's reason, says that the monitor is still disabled,
and tells the agent not to retry until the budget changes or another
monitor is disabled.

Other validation errors are unchanged. The check reads `detail` because
`@sentry/api` drops the parsed body for errors that have no `detail`
field.

Author: wedamija

packages/mcp-core/src/tools/catalog/update-uptime-monitor.test.ts

@@ -1,6 +1,8 @@
 import { mswServer } from "@sentry/mcp-server-mocks";
 import { HttpResponse, http } from "msw";
 import { describe, expect, it } from "vitest";
+import { ApiValidationError } from "../../api-client/index.js";
+import { UserInputError } from "../../errors.js";
 import {
   assertStructuredOnlyResult,
   getStructuredContent,
@@ -62,6 +64,66 @@ describe("update_uptime_monitor", () => {
     `);
   });
 
+  it("explains how to get a seat when enabling fails", async () => {
+    mswServer.use(
+      http.put(
+        "https://sentry.io/api/0/projects/sentry-mcp-evals/cloudflare-mcp/uptime/4509100000001001/",
+        () =>
+          HttpResponse.json(
+            {
+              status: [
+                "You don't have enough pay-as-you-go available to create a new seat",
+              ],
+            },
+            { status: 400 },
+          ),
+      ),
+    );
+
+    const error = await updateUptimeMonitor
+      .handler(
+        {
+          organizationSlug: "sentry-mcp-evals",
+          regionUrl: null,
+          projectSlug: "cloudflare-mcp",
+          uptimeMonitorId: "4509100000001001",
+          status: "active",
+        },
+        context,
+      )
+      .catch((e: unknown) => e);
+
+    expect(error).toBeInstanceOf(UserInputError);
+    expect((error as Error).message).toContain(
+      "You don't have enough pay-as-you-go available to create a new seat",
+    );
+    expect((error as Error).message).toContain("Do not retry");
+  });
+
+  it("does not treat other validation errors as seat errors", async () => {
+    mswServer.use(
+      http.put(
+        "https://sentry.io/api/0/projects/sentry-mcp-evals/cloudflare-mcp/uptime/4509100000001001/",
+        () => HttpResponse.json({ url: ["Invalid URL"] }, { status: 400 }),
+      ),
+    );
+
+    const error = await updateUptimeMonitor
+      .handler(
+        {
+          organizationSlug: "sentry-mcp-evals",
+          regionUrl: null,
+          projectSlug: "cloudflare-mcp",
+          uptimeMonitorId: "4509100000001001",
+          status: "active",
+        },
+        context,
+      )
+      .catch((e: unknown) => e);
+
+    expect(error).toBeInstanceOf(ApiValidationError);
+  });
+
   it("clears owner when null is provided", async () => {
     let requestBody: Record<string, unknown> | null = null;
     mswServer.use(

packages/mcp-core/src/tools/catalog/update-uptime-monitor.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ApiValidationError } from "../../api-client/index";
 import { UserInputError } from "../../errors";
 import { apiServiceFromContext } from "../../internal/tool-helpers/api";
 import { defineTool } from "../../internal/tool-helpers/define";
@@ -27,6 +28,21 @@ export const updateUptimeMonitorOutputSchema = z.object({
   monitor: uptimeMonitorSummarySchema,
 });
 
+const seatErrorSchema = z.object({ status: z.array(z.string()).min(1) });
+
+// The API client only keeps a field error's body as raw text in `detail`.
+function getSeatErrorReason(error: unknown): string | undefined {
+  if (!(error instanceof ApiValidationError) || !error.detail) {
+    return undefined;
+  }
+  try {
+    const parsed = seatErrorSchema.safeParse(JSON.parse(error.detail));
+    return parsed.success ? parsed.data.status[0] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function hasDefinedUpdate(
   value: unknown,
 ): value is Exclude<typeof value, undefined> {
@@ -138,25 +154,36 @@ export default defineTool({
       );
     }
 
-    const monitor = await apiService.updateUptimeMonitor({
-      organizationSlug,
-      projectSlug: params.projectSlug,
-      uptimeMonitorId: params.uptimeMonitorId,
-      name: params.name,
-      url: params.url,
-      intervalSeconds: params.intervalSeconds,
-      timeoutMs: params.timeoutMs,
-      method: params.method,
-      headers: params.headers && toUptimeHeaderPairs(params.headers),
-      body: params.body,
-      status: params.status,
-      owner: params.owner,
-      environment: params.environment,
-      traceSampling: params.traceSampling,
-      responseCaptureEnabled: params.responseCaptureEnabled,
-      recoveryThreshold: params.recoveryThreshold,
-      downtimeThreshold: params.downtimeThreshold,
-    });
+    const monitor = await apiService
+      .updateUptimeMonitor({
+        organizationSlug,
+        projectSlug: params.projectSlug,
+        uptimeMonitorId: params.uptimeMonitorId,
+        name: params.name,
+        url: params.url,
+        intervalSeconds: params.intervalSeconds,
+        timeoutMs: params.timeoutMs,
+        method: params.method,
+        headers: params.headers && toUptimeHeaderPairs(params.headers),
+        body: params.body,
+        status: params.status,
+        owner: params.owner,
+        environment: params.environment,
+        traceSampling: params.traceSampling,
+        responseCaptureEnabled: params.responseCaptureEnabled,
+        recoveryThreshold: params.recoveryThreshold,
+        downtimeThreshold: params.downtimeThreshold,
+      })
+      .catch((error: unknown) => {
+        const reason = params.status === "active" && getSeatErrorReason(error);
+        if (reason) {
+          throw new UserInputError(
+            `Could not enable this uptime monitor: ${reason}. The monitor is still disabled. Do not retry until a billing admin raises the organization's pay-as-you-go budget in Sentry's billing settings, or another uptime monitor is disabled.`,
+            { cause: error },
+          );
+        }
+        throw error;
+      });
 
     return structuredResult({
       monitor: toUptimeMonitorSummary(