How to handle unexpected responses in the client?

[spietras]

Let's say I am using RPCHandler and RPCLink. When performing any operation, the underlying HTTP request and response with the underlying data will be based on the protocol designed by oRPC.

Everything works fine when the client can communicate directly with the server. But what if you introduce a middleman who can change something and break the expectation?

What I have in mind specifically for my case is that all my requests from the client to the server will go through a gateway that, for example, will check if the session is still valid and, if not, will respond with 401 Unauthorized directly.

So I am thinking: can I change something in the client, so that I could map these custom unexpected responses to something understandable by oRPC? In this case, mapping that 401 Unauthorized from the gateway to ORPCError with UNAUTHORIZED code.

This library looks so well thought out that no doubt this is possible, so rather the question is: what is the best way to do it?

[dosubot[bot]]

Hi @spietras! I'm Dosu and I’m helping the orpc team.

You can handle unexpected HTTP responses (like a 401 from your gateway) in the oRPC client by using interceptors—specifically, the onError handler—when configuring your RPCLink or client. This lets you catch and transform errors before they reach your application code.

For example, you can map a 401 Unauthorized response to an ORPCError with the UNAUTHORIZED code like this:

import { RPCLink, onError, ORPCError } from 'orpc';

const link = new RPCLink({
  interceptors: [
    onError((error) => {
      // If the error is an HTTP 401, map it to an ORPCError with code 'UNAUTHORIZED'
      if (error?.status === 401) {
        throw new ORPCError('UNAUTHORIZED', {
          status: 401,
          message: 'Session expired or unauthorized',
        });
      }
      // Optionally, rethrow other errors unchanged
      throw error;
    }),
  ],
});

This pattern is recommended and aligns with how oRPC suggests handling and transforming errors globally in the client. You can adapt the logic inside onError to handle other custom responses as needed. See more examples and discussion in this issue and here.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[spietras]

@dosu

1. I see there is interceptors, clientInterceptors and adapterInterceptors. What's the difference? Which one should I use and why?
2. When exactly is onError called? What exactly is inside the error parameter?
3. Should I use isDefinedError inside to differentiate between expected and unexpected errors?

[dosubot[bot]]

Here’s a breakdown of the three interceptor types in oRPC and how to handle error mapping:

1. interceptors run first and wrap the entire request lifecycle at a high level (before encoding, sending, and decoding). Use these for broad concerns like logging, tracing, or global error handling that applies to all requests, regardless of transport.
2. clientInterceptors run after interceptors and wrap the actual sending of the request and receiving the response (typically at the HTTP/request level). This is the best place to handle HTTP-specific logic—like mapping a 401 Unauthorized from your gateway to an ORPCError with code UNAUTHORIZED, adding headers, batching, or deduplication.
3. adapterInterceptors are specific to the network/protocol adapter (e.g., fetch) and let you intercept and modify low-level HTTP requests and responses before the actual network call. Use these for things like custom fetch logic or manipulating raw requests/responses.
   See the order and usage in the StandardLink implementation and LinkFetchClient.

onError is typically implemented as a clientInterceptor. It’s called whenever an error is thrown during the request/response lifecycle—this could be an ORPCError, a network error, or something else. The error parameter contains the thrown error object, which you can inspect for properties like code, status, name, and cause (example).

isDefinedError is recommended for reliably distinguishing expected/known oRPC errors from unexpected errors, especially in global error interceptors. It checks if the error is an instance of ORPCError and has the defined property set to true (source). This is especially useful if you want to handle only “known” errors and let others bubble up or be logged.

Best practice: For your use case (mapping gateway 401s), use a clientInterceptor with onError, check the error, and transform it as needed. Use isDefinedError if you want to differentiate between expected oRPC errors and unexpected ones.

Let me know if you want a code sample for a specific scenario!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[SyedaEmanSaleem]

You can intercept responses in the client and map custom HTTP codes (like 401) to ORPCError with the appropriate code, using a middleware or error hook is the cleanest approach.