From 0f2d930c7057457b7d33d6636f6fe3b5bba68cef Mon Sep 17 00:00:00 2001
From: s1gr1d <32902192+s1gr1d@users.noreply.github.com>
Date: Fri, 29 May 2026 14:12:53 +0200
Subject: [PATCH] docs(hono): Document `shouldHandleError` option

---
 .../guides/hono/features/error-handler.mdx    | 103 ++++++++++++++++++
 .../javascript/guides/hono/features/index.mdx |   9 ++
 .../javascript/guides/hono/index.mdx          |   3 +
 3 files changed, 115 insertions(+)
 create mode 100644 docs/platforms/javascript/guides/hono/features/error-handler.mdx
 create mode 100644 docs/platforms/javascript/guides/hono/features/index.mdx

diff --git a/docs/platforms/javascript/guides/hono/features/error-handler.mdx b/docs/platforms/javascript/guides/hono/features/error-handler.mdx
new file mode 100644
index 00000000000000..39ff4d686550df
--- /dev/null
+++ b/docs/platforms/javascript/guides/hono/features/error-handler.mdx
@@ -0,0 +1,103 @@
+---
+title: Error Handler
+description: "Learn how Sentry's Hono SDK captures errors and how to customize which errors are sent to Sentry."
+---
+
+The `sentry()` middleware automatically captures unhandled errors from Hono's `onError` handler.
+
+Use `shouldHandleError` when you need to capture errors outside this default range, for example to track 401 and 403 responses as security signals.
+
+## Configuration
+
+Pass a `shouldHandleError` callback to the `sentry()` middleware. The callback receives the raw error as `unknown` and must return `true` to capture it or `false` to suppress it.
+
+```typescript {tabTitle:Cloudflare Workers} {filename:index.ts} {mdExpandTabs}
+import { Hono } from "hono";
+import { sentry } from "@sentry/hono/cloudflare";
+
+const app = new Hono();
+
+app.use(
+  sentry(app, {
+    dsn: "___PUBLIC_DSN___",
+    shouldHandleError(error) {
+      const status = (error as { status?: number })?.status;
+      // Capture 401/403 in addition to the default 5xx errors
+      return (
+        status === 401 ||
+        status === 403 ||
+        typeof status !== "number" ||
+        status >= 500
+      );
+    },
+  })
+);
+
+export default app;
+```
+
+```typescript {tabTitle:Node.js} {filename:app.ts}
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+import { sentry } from "@sentry/hono/node";
+
+const app = new Hono();
+
+app.use(
+  sentry(app, {
+    shouldHandleError(error) {
+      const status = (error as { status?: number })?.status;
+      // Capture 401/403 in addition to the default 5xx errors
+      return (
+        status === 401 ||
+        status === 403 ||
+        typeof status !== "number" ||
+        status >= 500
+      );
+    },
+  })
+);
+
+// Your routes here
+
+serve(app);
+```
+
+```typescript {tabTitle:Bun} {filename:index.ts}
+import { Hono } from "hono";
+import { sentry } from "@sentry/hono/bun";
+
+const app = new Hono();
+
+app.use(
+  sentry(app, {
+    dsn: "___PUBLIC_DSN___",
+    shouldHandleError(error) {
+      const status = (error as { status?: number })?.status;
+      // Capture 401/403 in addition to the default 5xx errors
+      return (
+        status === 401 ||
+        status === 403 ||
+        typeof status !== "number" ||
+        status >= 500
+      );
+    },
+  })
+);
+
+export default app;
+```
+
+## Default Behavior
+
+The default logic checks whether the error carries a numeric `status` property (as Hono's `HTTPException` and similar error types do).
+Errors in the 3xx–4xx range are skipped; everything else is captured.
+
+Without `shouldHandleError`, the middleware captures:
+
+- **5xx errors**: Anything with a numeric `status >= 500`
+- **Non-HTTP errors**: Errors without a numeric `status` property, including standard `Error` instances, non-object throws, and `null`
+
+The middleware ignores:
+
+- **3xx–4xx errors**: Anything with a numeric `status` in the range 300–499 (redirects, client errors)
diff --git a/docs/platforms/javascript/guides/hono/features/index.mdx b/docs/platforms/javascript/guides/hono/features/index.mdx
new file mode 100644
index 00000000000000..0580f8f8c3f5d2
--- /dev/null
+++ b/docs/platforms/javascript/guides/hono/features/index.mdx
@@ -0,0 +1,9 @@
+---
+title: Hono Features
+description: "Learn how Sentry's Hono SDK exposes features for first-class integration with Hono."
+excerpt: ""
+---
+
+The Sentry Hono SDK offers Hono-specific features for first-class integration with the framework.
+
+<PageGrid />
diff --git a/docs/platforms/javascript/guides/hono/index.mdx b/docs/platforms/javascript/guides/hono/index.mdx
index aee4767784acaf..86fff01274834c 100644
--- a/docs/platforms/javascript/guides/hono/index.mdx
+++ b/docs/platforms/javascript/guides/hono/index.mdx
@@ -363,6 +363,8 @@ export default app;
 
 By default, Sentry captures exceptions from Hono's `onError` handler, excluding errors with 3xx or 4xx status codes. No additional configuration is needed for this.
 
+To control which errors are captured, use the <PlatformLink to="/features/error-handler/">`shouldHandleError`</PlatformLink> option.
+
 ### Add Readable Stack Traces With Source Maps (Optional)
 
 <PlatformContent includePath="getting-started-sourcemaps-short-version" />
@@ -385,6 +387,7 @@ Now's a good time to customize your setup and look into more advanced topics:
 
 - Explore [practical guides](/guides/) on what to monitor, log, track, and investigate after setup
 - Learn how to <PlatformLink to="/usage">manually capture errors</PlatformLink>
+- Explore <PlatformLink to="/features">Hono-specific features</PlatformLink> like custom error filtering
 - Continue to <PlatformLink to="/configuration">customize your configuration</PlatformLink>
 - Get familiar with [Sentry's product features](/product) like tracing, insights, and alerts