feat(client): introduce ResponseError for carrying response details

[dinwwwh]

Summary

Introduce a new ResponseError class that carries resolved response details (status, headers, body) when links encounter error responses. This allows callers to access response metadata that isn't part of the error itself, such as status codes and headers.

Changes

• New ResponseError class: A lightweight error that wraps response details, used as the cause of ORPCError instances decoded from error responses
• Refactored MalformedResponseError: Now extends ResponseError instead of Error, eliminating duplicate response handling logic
• Updated link codecs: Both RPCLinkCodec and OpenAPILinkCodec now attach a ResponseError as the cause when decoding error responses, making response metadata available to error handlers
• Documentation: Added "Error Responses" sections to RPC and OpenAPI link docs with examples of accessing response details via the cause chain
• Tests: Added comprehensive tests for ResponseError and updated existing tests to verify the cause chain

Implementation Details

• ResponseError infers a default message from the response status (e.g., "Received a 404 response.") when no custom message is provided
• MalformedResponseError now delegates to ResponseError's constructor, reducing code duplication
• The response is attached as cause rather than thrown directly, preserving the primary error (ORPCError) while keeping response details accessible
• Both RPC and OpenAPI links follow the same pattern for consistency

https://claude.ai/code/session_01RggAhK2fPDzS1W965ZaJQY

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	orpc	4a90670	Commit Preview URL Branch Preview URL	Oct 19 2026, 08:12 AM

[pullfrog]

✅ No new issues found.

Reviewed changes — Introduces a public ResponseError carrying the resolved response and attaches it as the cause of ORPCErrors decoded from error responses; MalformedResponseError is refactored to extend it; docs and tests updated.

• New ResponseError class (packages/client/src/error.ts:173) — extends Error, exposes response, and defaults its message to Received a ${status} response.; ResponseErrorOptions is extracted from the old malformed options.
• MalformedResponseError extends ResponseError (packages/client/src/error.ts:204) — drops its duplicated response field while preserving message inference and name.
• RPC and OpenAPI link codecs (rpc-link-codec.ts:147, openapi-link-codec.ts:410) — attach a ResponseError as cause when the error body is an ORPCError-shaped JSON; the OpenAPI customErrorResponseBodyDecoder path still returns its error as-is.
• Docs + tests — new "Error Responses" sections in both link docs (anchors match the JSDoc @see links); tests assert the cause chain and that it is a plain ResponseError, not a MalformedResponseError.

Verified locally: the affected tests pass and @orpc/client / @orpc/openapi type-check cleanly. No framework source branches on the absence of error.cause, so attaching one is non-breaking for existing consumers.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[pkg-pr-new]

More templates

• @orpc/bun-playground
• @orpc/cloudflare-playground
• @orpc/nest-playground
• @orpc/next-playground

@orpc/ai-sdk

npm i https://pkg.pr.new/@orpc/ai-sdk@2265

@orpc/arktype

npm i https://pkg.pr.new/@orpc/arktype@2265

@orpc/bun

npm i https://pkg.pr.new/@orpc/bun@2265

@orpc/client

npm i https://pkg.pr.new/@orpc/client@2265

@orpc/cloudflare

npm i https://pkg.pr.new/@orpc/cloudflare@2265

@orpc/contract

npm i https://pkg.pr.new/@orpc/contract@2265

@orpc/experimental-effect

npm i https://pkg.pr.new/@orpc/experimental-effect@2265

@orpc/evlog

npm i https://pkg.pr.new/@orpc/evlog@2265

@orpc/hibernation

npm i https://pkg.pr.new/@orpc/hibernation@2265

@orpc/json-schema

npm i https://pkg.pr.new/@orpc/json-schema@2265

@orpc/experimental-lock

npm i https://pkg.pr.new/@orpc/experimental-lock@2265

@orpc/experimental-msw

npm i https://pkg.pr.new/@orpc/experimental-msw@2265

@orpc/nest

npm i https://pkg.pr.new/@orpc/nest@2265

@orpc/next

npm i https://pkg.pr.new/@orpc/next@2265

@orpc/node

npm i https://pkg.pr.new/@orpc/node@2265

@orpc/openapi

npm i https://pkg.pr.new/@orpc/openapi@2265

@orpc/opentelemetry

npm i https://pkg.pr.new/@orpc/opentelemetry@2265

@orpc/pinia-colada

npm i https://pkg.pr.new/@orpc/pinia-colada@2265

@orpc/pino

npm i https://pkg.pr.new/@orpc/pino@2265

@orpc/publisher

npm i https://pkg.pr.new/@orpc/publisher@2265

@orpc/ratelimit

npm i https://pkg.pr.new/@orpc/ratelimit@2265

@orpc/server

npm i https://pkg.pr.new/@orpc/server@2265

@orpc/shared

npm i https://pkg.pr.new/@orpc/shared@2265

@orpc/swr

npm i https://pkg.pr.new/@orpc/swr@2265

@orpc/tanstack-query

npm i https://pkg.pr.new/@orpc/tanstack-query@2265

@orpc/trpc

npm i https://pkg.pr.new/@orpc/trpc@2265

@orpc/valibot

npm i https://pkg.pr.new/@orpc/valibot@2265

@orpc/zod

npm i https://pkg.pr.new/@orpc/zod@2265

commit: 4a90670

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will not alter performance

⚠️ 6 benchmarks spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

• range request
• not modified (304)
• serve deeply nested encoded path
• serve file
• 5MB payload
• not found fall through

✅ 28 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing claude/sleepy-cerf-0hsbvy (4a90670) with main (0c7f63b)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩