From 315768a5883be019e0d1d83b7102c5a2eba5fc21 Mon Sep 17 00:00:00 2001
From: mathuraditya724 <mathuraditya724@gmail.com>
Date: Sun, 6 Sep 2026 11:49:25 +0530
Subject: [PATCH] fix(docs): Explain regional model unavailability

---
 packages/cli/src/lib/docs-service.ts       |  6 +++++
 packages/cli/test/lib/docs-service.test.ts | 26 ++++++++++++++++++++++
 2 files changed, 32 insertions(+)

diff --git a/packages/cli/src/lib/docs-service.ts b/packages/cli/src/lib/docs-service.ts
index 2acd899fb..6739344bd 100644
--- a/packages/cli/src/lib/docs-service.ts
+++ b/packages/cli/src/lib/docs-service.ts
@@ -48,6 +48,12 @@ async function postDocs<T>(
         EXIT.API
       );
     }
+    if (parsed?.code === "DOCS_MODEL_UNAVAILABLE") {
+      throw new CliError(
+        "Sentry Docs AI is temporarily unavailable in this region. Please try again later.",
+        EXIT.API
+      );
+    }
     if (typeof parsed?.error === "string") {
       detail = parsed.error;
     }
diff --git a/packages/cli/test/lib/docs-service.test.ts b/packages/cli/test/lib/docs-service.test.ts
index f97d062ea..73a521869 100644
--- a/packages/cli/test/lib/docs-service.test.ts
+++ b/packages/cli/test/lib/docs-service.test.ts
@@ -17,6 +17,32 @@ import { queryDocs } from "../../src/lib/docs-service.js";
 import { EXIT, isUserError } from "../../src/lib/errors.js";
 
 describe("queryDocs", () => {
+  test("explains when Docs AI is unavailable in the service region", async () => {
+    refreshToken.mockResolvedValue({ token: "test-token" });
+    customFetch.mockResolvedValue({
+      ok: false,
+      status: 502,
+      text: vi.fn().mockResolvedValue(
+        JSON.stringify({
+          code: "DOCS_MODEL_UNAVAILABLE",
+          error: "Sentry Docs AI is temporarily unavailable in this region.",
+        })
+      ),
+    });
+
+    await expect(
+      queryDocs("How do I configure tracing?", {
+        frameworks: [],
+        languages: [],
+        sentryConfigured: false,
+      })
+    ).rejects.toMatchObject({
+      exitCode: EXIT.API,
+      message:
+        "Sentry Docs AI is temporarily unavailable in this region. Please try again later.",
+    });
+  });
+
   test("explains when the service cannot verify a cited answer", async () => {
     refreshToken.mockResolvedValue({ token: "test-token" });
     customFetch.mockResolvedValue({