Enhance error handling and API response for documentation tools

mantrakp04 · mantrakp04 · commit 50787475a29f · 2026-03-23T17:13:35.000-07:00
- 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.
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" } },
   );
 }

Original file line number	Diff line number	Diff line change
`@@ -50,6 +50,6 @@ export async function POST(req: NextRequest) {`
`50`	`50`	`export async function GET() {`
`51`	`51`	`return NextResponse.json(`
`52`	`52`	`{ error: "Use POST with a DocsToolAction body" },`
`53`		`- { status: 405 },`
	`53`	`+ { status: 405, headers: { Allow: "POST" } },`
`54`	`54`	`);`
`55`	`55`	`}`