Enhance error handling and API response for documentation tools

- Introduced error capturing for failed HTTP requests in the docs tools API, improving debugging capabilities. - Updated the API response for unsupported methods to include an 'Allow' header, clarifying the expected request type. These changes enhance the robustness of the documentation tools integration and improve developer experience.
stack-auth · mantrakp04 · Apr 12, 2026 · Mar 23, 2026 · Mar 23, 2026 · Mar 24, 2026
commit 50787475a29f3941843bd9d774d8909fa9694c43
diff --git a/apps/backend/src/lib/ai/tools/docs.ts b/apps/backend/src/lib/ai/tools/docs.ts
@@ -1,5 +1,6 @@
 import { tool } from "ai";
 import { getEnvVariable, getNodeEnvironment } from "@stackframe/stack-shared/dist/utils/env";
+import { captureError } from "@stackframe/stack-shared/dist/utils/errors";
 import { z } from "zod";
 
 type DocsToolHttpResult = {
@@ -22,11 +23,9 @@ function getDocsToolsBaseUrl(): string {
 async function postDocsToolAction(action: Record<string, unknown>): Promise<string> {
   const base = getDocsToolsBaseUrl();
   const secret = getEnvVariable("STACK_INTERNAL_DOCS_TOOLS_SECRET", "");
-  const headers: Record<string, string> = {
-    "Content-Type": "application/json",
-  };
+  const headers = new Headers({ "Content-Type": "application/json" });
   if (secret !== "") {
-    headers["x-stack-internal-docs-tools-secret"] = secret;
+    headers.set("x-stack-internal-docs-tools-secret", secret);
   }
 
   const res = await fetch(`${base}/api/internal/docs-tools`, {
@@ -37,6 +36,7 @@ async function postDocsToolAction(action: Record<string, unknown>): Promise<stri
 
   if (!res.ok) {
     const errBody = await res.text();
+    captureError("docs-tools-http-error", new Error(`Stack Auth docs tools error (${res.status}): ${errBody}`));
     return `Stack Auth docs tools error (${res.status}): ${errBody}`;
   }
 

diff --git a/docs/src/app/api/internal/docs-tools/route.ts b/docs/src/app/api/internal/docs-tools/route.ts
@@ -50,6 +50,6 @@ export async function POST(req: NextRequest) {
 export async function GET() {
   return NextResponse.json(
     { error: "Use POST with a DocsToolAction body" },
-    { status: 405 },
+    { status: 405, headers: { Allow: "POST" } },
   );
 }