docs: Customizing Error Response Format

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' },
           ],
         },
       ],

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
+    },
+  ],
+})
+```

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
 ```