From 832bda0b826d60b38776b522a290c394a9d9fa07 Mon Sep 17 00:00:00 2001
From: unnoq <contact@unnoq.com>
Date: Fri, 4 Jul 2025 15:25:14 +0700
Subject: [PATCH 1/2] improve handler interceptor

---
 apps/content/docs/rpc-handler.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/apps/content/docs/rpc-handler.md b/apps/content/docs/rpc-handler.md
index 4994bffad..b48084958 100644
--- a/apps/content/docs/rpc-handler.md
+++ b/apps/content/docs/rpc-handler.md
@@ -112,6 +112,7 @@ sequenceDiagram
 
   Note over A1: adaptorInterceptors
   A1 ->> P3: request
+  P3 ->> P3: Convert
   Note over P3: rootInterceptors
   P3 ->> P4: standard request
   Note over P4: interceptors
@@ -123,8 +124,11 @@ sequenceDiagram
   P4 ->> P5: Input, Signal, LastEventId,...
   Note over P5: clientInterceptors
   P5 ->> P5: Handle
-  P5 ->> P4: Error/Output
-  P4 ->> P4: Encode Error/Output
+  P5 ->> P4: if success
+  P4 ->> P4: Encode output
+  P5 ->> P4: if failed
+  Note over P4: end interceptors
+  P4 ->> P4: Encode error
   P4 ->> P3: standard response
   P3 ->> A1: response
 ```

From e2890bc94eed4e5d967815a55f7d4cb528f37ae1 Mon Sep 17 00:00:00 2001
From: unnoq <contact@unnoq.com>
Date: Fri, 4 Jul 2025 15:59:07 +0700
Subject: [PATCH 2/2] docs: Customizing Error Response Format

---
 apps/content/.vitepress/config.ts             |  3 +-
 .../advanced/customizing-error-response.md    | 43 +++++++++++++++++++
 2 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100644 apps/content/docs/openapi/advanced/customizing-error-response.md

diff --git a/apps/content/.vitepress/config.ts b/apps/content/.vitepress/config.ts
index 55f995d78..679499124 100644
--- a/apps/content/.vitepress/config.ts
+++ b/apps/content/.vitepress/config.ts
@@ -230,8 +230,9 @@ export default withMermaid(defineConfig({
           text: 'Advanced',
           collapsed: true,
           items: [
-            { text: 'Redirect Response', link: '/docs/openapi/advanced/redirect-response' },
+            { text: 'Customizing Error Response', link: '/docs/openapi/advanced/customizing-error-response' },
             { text: 'OpenAPI JSON Serializer', link: '/docs/openapi/advanced/openapi-json-serializer' },
+            { text: 'Redirect Response', link: '/docs/openapi/advanced/redirect-response' },
           ],
         },
       ],
diff --git a/apps/content/docs/openapi/advanced/customizing-error-response.md b/apps/content/docs/openapi/advanced/customizing-error-response.md
new file mode 100644
index 000000000..92473766c
--- /dev/null
+++ b/apps/content/docs/openapi/advanced/customizing-error-response.md
@@ -0,0 +1,43 @@
+---
+title: Customizing Error Response Format
+description: Learn how to customize the error response format in oRPC OpenAPI handlers to match your application's requirements and improve client compatibility.
+---
+
+# Customizing Error Response Format
+
+If you need to customize the error response format to match your application's requirements, you can use [`rootInterceptors`](/docs/rpc-handler#lifecycle) in the handler.
+
+::: warning
+Avoid combining this with [Type‑Safe Error Handling](/docs/error-handling#type‐safe-error-handling), as the [OpenAPI Specification Generator](/docs/openapi/openapi-specification) does not yet support custom error response formats.
+:::
+
+```ts
+import { isORPCErrorJson, isORPCErrorStatus } from '@orpc/client'
+
+const handler = new OpenAPIHandler(router, {
+  rootInterceptors: [
+    async ({ next }) => {
+      const result = await next()
+
+      if (
+        result.matched
+        && isORPCErrorStatus(result.response.status)
+        && isORPCErrorJson(result.response.body)
+      ) {
+        return {
+          ...result,
+          response: {
+            ...result.response,
+            body: {
+              ...result.response.body,
+              message: 'custom error shape',
+            },
+          },
+        }
+      }
+
+      return result
+    },
+  ],
+})
+```