feat(rpc, openapi): improve malformed response handling in RPCLink and OpenAPILink (#1836)

Malformed responses, such as a proxy or gateway answering instead of the
handler, now surface as an identifiable `MALFORMED_ORPC_RESPONSE`
`ORPCError` with a meaningful message instead of a generic one. Its
`cause` is a new `MalformedResponseError` carrying the typed resolved
response, so users can detect this case the same way they detect
validation errors.

## Changes

- The error message is inferred from the response body (a string body,
or a string `body.message`) or from the common error code matching the
status; the previous behavior always used the generic default message.
- A shared `createORPCErrorFromMalformedResponse(options)` helper in
`@orpc/client` now backs both `RPCLinkCodec` and `OpenAPILinkCodec`,
accepting the same options shape as `MalformedResponseError`.
- Deserialization failures (`Invalid RPC response format.` / `Invalid
OpenAPI response format.`) throw the same error with the raw resolved
body attached, so the actual server payload is no longer lost (the RPC
deserializer turns unknown JSON into `undefined`).
- `OpenAPILinkCodec` resolves the body outside try/catch like
`RPCLinkCodec`, so body-read failures propagate the original error
instead of the `Cannot parse response body` wrapper.
- New "Malformed Responses" sections in the RPCLink and OpenAPILink docs
show identifying the case from a link interceptor.

## Breaking

- The error code `MALFORMED_ORPC_ERROR_RESPONSE` is renamed to
`MALFORMED_ORPC_RESPONSE`, since it now also covers success responses
that fail to deserialize.
- The `data` attached to the error is now the raw resolved body rather
than the RPC/OpenAPI-deserialized value.

## Testing

- Unit tests cover every message-inference path, the cause identity, and
both codecs' malformed paths; all 901 client + openapi tests pass, along
with `type:check`, `lint`, and `docs:validate`.

Author: dinwwwh

apps/content/docs/openapi/link.mdx

@@ -269,6 +269,24 @@ const link = new OpenAPILink(contract, {
 })
 ```
 
+## Malformed Responses
+
+When `OpenAPILink` cannot decode a response, for example when a proxy or gateway answers instead of your handler, it produces an `ORPCError` with code `MALFORMED_ORPC_RESPONSE` and a message inferred from the body or status. Its `cause` is a `MalformedResponseError` carrying the resolved response:
+
+```ts
+import { MalformedResponseError, ORPCError, onError } from '@orpc/client'
+
+const link = new OpenAPILink(contract, {
+  interceptors: [
+    onError((error) => {
+      if (error instanceof ORPCError && error.cause instanceof MalformedResponseError) {
+        console.error('Malformed response:', error.cause.response.status, error.cause.response.body)
+      }
+    }),
+  ],
+})
+```
+
 ## Event Stream Options
 
 Configure how an [AsyncIteratorObject](/docs/async-iterator-object) is streamed to the server. Available options depend on the adapter. For example, the fetch adapter supports:

apps/content/docs/rpc/link.mdx

@@ -294,6 +294,24 @@ const link = new RPCLink<ClientContext>({
 })
 ```
 
+## Malformed Responses
+
+When `RPCLink` cannot decode a response, for example when a proxy or gateway answers instead of your handler, it produces an `ORPCError` with code `MALFORMED_ORPC_RESPONSE` and a message inferred from the body or status. Its `cause` is a `MalformedResponseError` carrying the resolved response:
+
+```ts
+import { MalformedResponseError, ORPCError, onError } from '@orpc/client'
+
+const link = new RPCLink({
+  interceptors: [
+    onError((error) => {
+      if (error instanceof ORPCError && error.cause instanceof MalformedResponseError) {
+        console.error('Malformed response:', error.cause.response.status, error.cause.response.body)
+      }
+    }),
+  ],
+})
+```
+
 ## Event Stream Options
 
 Configure how an [AsyncIteratorObject](/docs/async-iterator-object) is streamed to the server. Available options depend on the adapter. For example, the fetch adapter supports:

packages/client/src/adapters/standard/index.ts

@@ -3,15 +3,3 @@ export * from './link'
 export * from './plugin'
 export * from './rpc-link-codec'
 export * from './transport'
-
-export type {
-  StandardBody,
-  StandardBodyHint,
-  StandardHeaders,
-  StandardLazyRequest,
-  StandardLazyResponse,
-  StandardMethod,
-  StandardRequest,
-  StandardResponse,
-  StandardUrl,
-} from '@standardserver/core'

packages/client/src/adapters/standard/rpc-link-codec.test.ts

@@ -1,5 +1,5 @@
 import type { StandardUrl } from '@standardserver/core'
-import { ORPCError } from '../../error'
+import { MalformedResponseError, ORPCError } from '../../error'
 import { RPCSerializer } from '../../rpc-serializer'
 import { RPCLinkCodec } from './rpc-link-codec'
 
@@ -272,7 +272,7 @@ describe('rpcLinkCodec', () => {
       })
     })
 
-    it('wraps non-ORPCError error response with generic MALFORMED_ORPC_ERROR_RESPONSE ORPCError', async () => {
+    it('wraps non-ORPCError error response with generic MALFORMED_ORPC_RESPONSE ORPCError', async () => {
       const serialized = serializer.serialize({ something: 'unexpected' })
 
       const result = await codec.decodeResponse({
@@ -284,21 +284,46 @@ describe('rpcLinkCodec', () => {
       expect(result.kind).toBe('error')
       if (result.kind === 'error') {
         expect(result.error).toBeInstanceOf(ORPCError)
-        expect(result.error.code).toBe('MALFORMED_ORPC_ERROR_RESPONSE')
+        expect(result.error.code).toBe('MALFORMED_ORPC_RESPONSE')
+        expect(result.error.message).toBe('Forbidden')
         expect(result.error.data).toEqual(expect.objectContaining({
           status: 403,
           headers: { 'x-header': 'value' },
-          body: { something: 'unexpected' },
+          body: serialized,
         }))
+        expect(result.error.cause).toBeInstanceOf(MalformedResponseError)
+        expect((result.error.cause as MalformedResponseError).response).toBe(result.error.data)
       }
     })
 
-    it('throws on invalid RPC response format', async () => {
-      await expect(codec.decodeResponse({
+    it('infers MALFORMED_ORPC_RESPONSE message from the response body', async () => {
+      const result = await codec.decodeResponse({
+        status: 400,
+        headers: {},
+        resolveBody: () => Promise.resolve({ message: 'upstream exploded' }),
+      })
+
+      expect(result.kind).toBe('error')
+      if (result.kind === 'error') {
+        expect(result.error.code).toBe('MALFORMED_ORPC_RESPONSE')
+        expect(result.error.message).toBe('upstream exploded')
+      }
+    })
+
+    it('throws MALFORMED_ORPC_RESPONSE on invalid RPC response format', async () => {
+      const error: any = await codec.decodeResponse({
         status: 200,
         headers: {},
         resolveBody: () => Promise.resolve({ meta: 123 }),
-      })).rejects.toThrow('Invalid RPC response format.')
+      }).then(() => null, e => e)
+
+      expect(error).toBeInstanceOf(ORPCError)
+      expect(error.code).toBe('MALFORMED_ORPC_RESPONSE')
+      expect(error.message).toBe('Invalid RPC response format.')
+      expect(error.data).toEqual({ status: 200, headers: {}, body: { meta: 123 } })
+      expect(error.cause).toBeInstanceOf(MalformedResponseError)
+      expect(error.cause.response).toBe(error.data)
+      expect(error.cause.cause).toBeInstanceOf(Error)
     })
   })
 })

packages/client/src/adapters/standard/rpc-link-codec.ts

@@ -1,12 +1,11 @@
 import type { Promisable, Value } from '@orpc/shared'
-import type { StandardHeaders, StandardLazyResponse, StandardRequest, StandardResponse, StandardUrl } from '@standardserver/core'
+import type { StandardHeaders, StandardLazyResponse, StandardRequest, StandardUrl } from '@standardserver/core'
 import type { ClientContext, ClientOptions } from '../../types'
 import type { StandardLinkCodec, StandardLinkCodecDecodedResponse } from '../standard'
 import { isAsyncIteratorObject, pathToHttpPath, stringifyJSON, value } from '@orpc/shared'
 import { mergeStandardHeaders, parseStandardUrl } from '@standardserver/core'
 import { toStandardHeaders } from '@standardserver/fetch'
-import { ORPCError } from '../../error'
-import { createORPCErrorFromJson, isORPCErrorJson } from '../../error-utils'
+import { createORPCErrorFromJson, createORPCErrorFromMalformedResponse, isORPCErrorJson } from '../../error-utils'
 import { RPCSerializer } from '../../rpc-serializer'
 
 export interface RPCLinkCodecOptions<T extends ClientContext> {
@@ -132,7 +131,9 @@ export class RPCLinkCodec<T extends ClientContext> implements StandardLinkCodec<
         return this.serializer.deserialize(body)
       }
       catch (cause) {
-        throw new Error('Invalid RPC response format.', {
+        throw createORPCErrorFromMalformedResponse({
+          message: 'Invalid RPC response format.',
+          response: { status: response.status, headers: response.headers, body },
           cause,
         })
       }
@@ -145,9 +146,7 @@ export class RPCLinkCodec<T extends ClientContext> implements StandardLinkCodec<
 
       return {
         kind: 'error',
-        error: new ORPCError<'MALFORMED_ORPC_ERROR_RESPONSE', StandardResponse>('MALFORMED_ORPC_ERROR_RESPONSE', {
-          data: { headers: response.headers, status: response.status, body: deserialized },
-        }),
+        error: createORPCErrorFromMalformedResponse({ response: { headers: response.headers, status: response.status, body } }),
       }
     }
 

packages/client/src/error-utils.test.ts

@@ -1,8 +1,9 @@
 import type { Writable } from '@orpc/shared'
-import { ORPCError } from './error'
+import { MalformedResponseError, ORPCError } from './error'
 import {
   cloneORPCError,
   createORPCErrorFromJson,
+  createORPCErrorFromMalformedResponse,
   isInferableError,
   isORPCErrorJson,
   toORPCError,
@@ -180,6 +181,71 @@ describe('createORPCErrorFromJson', () => {
   })
 })
 
+describe('createORPCErrorFromMalformedResponse', () => {
+  it('creates a MALFORMED_ORPC_RESPONSE error with the response as data and a MalformedResponseError cause', () => {
+    const response = { status: 500, headers: { 'x-header': 'value' }, body: { something: 'unexpected' } }
+    const error = createORPCErrorFromMalformedResponse({ response })
+
+    expect(error).toBeInstanceOf(ORPCError)
+    expect(error.code).toBe('MALFORMED_ORPC_RESPONSE')
+    expect(error.defined).toBe(false)
+    expect(error.data).toBe(response)
+    expect(error.cause).toBeInstanceOf(MalformedResponseError)
+    expect((error.cause as MalformedResponseError).name).toBe('MalformedResponseError')
+    expect((error.cause as MalformedResponseError).response).toBe(response)
+    expect((error.cause as MalformedResponseError).message).toBe(error.message)
+  })
+
+  it('supports overriding the message and forwarding a cause to the MalformedResponseError', () => {
+    const cause = new Error('deserialize failed')
+    const error = createORPCErrorFromMalformedResponse({
+      message: 'Invalid RPC response format.',
+      response: { status: 200, headers: {}, body: 'not rpc format' },
+      cause,
+    })
+
+    expect(error.message).toBe('Invalid RPC response format.')
+    expect((error.cause as MalformedResponseError).message).toBe('Invalid RPC response format.')
+    expect((error.cause as MalformedResponseError).cause).toBe(cause)
+  })
+
+  it('infers message from a string body', () => {
+    const error = createORPCErrorFromMalformedResponse({ response: { status: 500, headers: {}, body: 'upstream exploded' } })
+
+    expect(error.message).toBe('upstream exploded')
+  })
+
+  it('infers message from body.message', () => {
+    const error = createORPCErrorFromMalformedResponse({ response: { status: 500, headers: {}, body: { message: 'upstream exploded', detail: 'ignored' } } })
+
+    expect(error.message).toBe('upstream exploded')
+  })
+
+  it('infers message from a common error code matching the status', () => {
+    expect(createORPCErrorFromMalformedResponse({ response: { status: 404, headers: {}, body: { detail: 'no message here' } } }).message).toBe('Not Found')
+    expect(createORPCErrorFromMalformedResponse({ response: { status: 503, headers: {}, body: undefined } }).message).toBe('Service Unavailable')
+  })
+
+  it('ignores bodies longer than 256 characters', () => {
+    const long = 'x'.repeat(257)
+
+    expect(createORPCErrorFromMalformedResponse({ response: { status: 502, headers: {}, body: long } }).message).toBe('Bad Gateway')
+    expect(createORPCErrorFromMalformedResponse({ response: { status: 502, headers: {}, body: { message: long } } }).message).toBe('Bad Gateway')
+  })
+
+  it.each([
+    ['empty string body', ''],
+    ['empty body.message', { message: '' }],
+    ['oversized string body', 'x'.repeat(257)],
+    ['non-string body.message', { message: 42 }],
+    ['non-object body', 42],
+  ])('falls back to the default message when the status is uncommon and the body has no message (%s)', (_, body) => {
+    const error = createORPCErrorFromMalformedResponse({ response: { status: 599, headers: {}, body } })
+
+    expect(error.message).toBe('Malformed Orpc Response')
+  })
+})
+
 describe('cloneORPCError', () => {
   it('creates a clone of ORPCError', () => {
     const original = new ORPCError('BAD_REQUEST', {

packages/client/src/error-utils.ts

@@ -1,7 +1,8 @@
 import type { Writable } from '@orpc/shared'
-import type { AnyORPCError, ORPCErrorCode, ORPCErrorJSON } from './error'
+import type { StandardResponse } from '@standardserver/core'
+import type { AnyORPCError, MalformedResponseErrorOptions, ORPCErrorCode, ORPCErrorJSON } from './error'
 import { isPlainObject } from '@orpc/shared'
-import { ORPCError } from './error'
+import { COMMON_ERROR_STATUS_MAP, MalformedResponseError, ORPCError } from './error'
 
 /**
  * Checks if an error is an `ORPCError` whose type is inferable at the TypeScript level,
@@ -54,6 +55,51 @@ export function createORPCErrorFromJson<TCode extends ORPCErrorCode, TData>(
   return error
 }
 
+/**
+ * Creates the `MALFORMED_ORPC_RESPONSE` `ORPCError` used when a response
+ * does not follow the expected oRPC format. Unless overridden via `options.message`,
+ * the message is inferred from the response body or status. The `cause` is a
+ * `MalformedResponseError` carrying the resolved response.
+ *
+ * @see {@link https://orpc.dev/docs/rpc/link#malformed-responses | RPC Link - Malformed Responses}
+ * @see {@link https://orpc.dev/docs/openapi/link#malformed-responses | OpenAPI Link - Malformed Responses}
+ */
+export function createORPCErrorFromMalformedResponse(options: MalformedResponseErrorOptions): ORPCError<'MALFORMED_ORPC_RESPONSE', StandardResponse> {
+  const error = new ORPCError('MALFORMED_ORPC_RESPONSE', {
+    message: options.message ?? inferMalformedResponseMessage(options.response),
+    data: options.response,
+  })
+
+  error.cause = new MalformedResponseError({ ...options, message: error.message })
+
+  return error
+}
+
+/**
+ * Bounds for using a body string as the error message,
+ * ignoring empty and unreasonably long values.
+ */
+const INFERRED_MESSAGE_MIN_LENGTH = 1
+const INFERRED_MESSAGE_MAX_LENGTH = 256
+
+function isInferableMessage(text: string): boolean {
+  return text.length >= INFERRED_MESSAGE_MIN_LENGTH && text.length <= INFERRED_MESSAGE_MAX_LENGTH
+}
+
+function inferMalformedResponseMessage(response: StandardResponse): string | undefined {
+  if (typeof response.body === 'string' && isInferableMessage(response.body)) {
+    return response.body
+  }
+
+  if (isPlainObject(response.body) && typeof response.body.message === 'string' && isInferableMessage(response.body.message)) {
+    return response.body.message
+  }
+
+  const commonCode = Object.entries(COMMON_ERROR_STATUS_MAP).find(([, status]) => status === response.status)?.[0]
+
+  return commonCode?.split('_').map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase()).join(' ')
+}
+
 /**
  * Clones an `ORPCError` while preserving its prototype chain, so instances of
  * `ORPCError` subclasses remain `instanceof` their class.

packages/client/src/error.ts

@@ -1,4 +1,5 @@
 import type { MaybeOptionalOptions, Registry } from '@orpc/shared'
+import type { StandardResponse } from '@standardserver/core'
 import { getConstructors, resolveMaybeOptionalOptions } from '@orpc/shared'
 
 /**
@@ -161,3 +162,28 @@ export interface ORPCErrorJSON<TCode extends string, TData> extends Pick<ORPCErr
 
 export type AnyORPCError = ORPCError<any, any>
 export type AnyORPCErrorJSON = ORPCErrorJSON<any, any>
+
+export interface MalformedResponseErrorOptions extends ErrorOptions {
+  message?: string
+  response: StandardResponse
+}
+
+/**
+ * Error indicating a response does not follow the expected oRPC format, carrying
+ * the resolved response. Found as the `cause` of a `MALFORMED_ORPC_RESPONSE`
+ * `ORPCError`.
+ *
+ * @see {@link https://orpc.dev/docs/rpc/link#malformed-responses | RPC Link - Malformed Responses}
+ * @see {@link https://orpc.dev/docs/openapi/link#malformed-responses | OpenAPI Link - Malformed Responses}
+ */
+export class MalformedResponseError extends Error {
+  override readonly name = 'MalformedResponseError'
+
+  response: StandardResponse
+
+  constructor(options: MalformedResponseErrorOptions) {
+    super(options.message, options)
+
+    this.response = options.response
+  }
+}

packages/client/src/index.ts

@@ -70,6 +70,15 @@ export type {
 
 export type {
   EventMeta,
+  StandardBody,
+  StandardBodyHint,
+  StandardHeaders,
+  StandardLazyRequest,
+  StandardLazyResponse,
+  StandardMethod,
+  StandardRequest,
+  StandardResponse,
+  StandardUrl,
 } from '@standardserver/core'
 
 export {