"correct" way to use both negative and positive responses

[HenriJ]

Hi @RobinTail , this topic is to help me better understand the "correct" way to use both negative and positive responses. I'd also like to share how I currently use express-zod-api to gain your insights.

1. Using http exceptions

My current understanding is that to trigger a negative response (i.e. a non-2xx status code), I need to throw an HTTP exception. This approach is common in many Node.js web frameworks (e.g., Nest), but it has always felt odd to me in scenarios where the situation isn't truly exceptional — such as returning a 404 for a non-existent resource. By using exceptions I am loosing the type-safety of return types (and probably reducing overall performance as exceptions come with some weight).

Because of this, I currently try to limit non-2xx responses to a very specific subset of cases. However, it can still be a challenge—for instance, during authentication, where I need to return different status codes for a 401 response and want them to be strongly typed without throwing errors (which does not seem possible ?).

I'm not sure if this approach would make sense for express-zod-api, but I recall using a framework where handlers explicitly returned a type like {status: number, headers, body}, which helped address this issue.

2. "RESTier" body return type

Right now, my result handler looks like

  positive: (data) => ({
    schema: data,
  }),
  negative: z.object({ error: z.string() }),

meaning when it is a 2xx, simply return the object and otherwise just share some untyped information about the error.

If my understanding is correct, we already know by using the HTTP status code if we are in the positive or negative case and don't need an additional status discriminator in the body for that.

The existing documentation is very helpful regarding this. I guess, my only feedback, is that the default behavior is a little bit surprising.

3. Generated client and positive/negative responses

In the generated client, the HTTP status code is not taken into account at all, although it could be a discriminator between positive and negative response.

I overloaded the client in my case to use the status code and always return the PositiveResponse as any other http status code (it's great you added the splitResponse flag for that!).
I guess, it could also make sense to overload the client to return {status: HTTPSTATUSCODE, body: WE_KNOW_IF_POSITIVE_OR_NEGATIVE}

[RobinTail]

Thank you for sharing, @HenriJ .

I encourage making custom client solutions by providing the Integration option variant: "types" and splitResponse: true, so that the generated output would have everything required to make a client suitable for your needs and your style of approaching such problems.

In my personal frontend engineering experience the status code is not as important as a binary fact of the response success.
That being said is also taking into account that successful response may not always have the status code 200, it can be 201 or 204 in some REST APIs. The error code can be 401 for Authorization error or 500 for internal error, but all that usually does not matter much, because it always lead to generic error handling. Basically, I'd either expect a valid data or an error. Both cases should be clear how to read and that's it.

Based on that experience I made the defaultResultHandler that puts the status discriminator right inside the payload, so that consumer would not even have to bother themselves with assessing anything else, but the payload only.

Regarding the errors.

it has always felt odd to me in scenarios where the situation isn't truly exceptional
By using exceptions I am loosing the type-safety of return types
exceptions come with some weight

I'm not sure I understand what exactly you mean and what the issue is.
The ResultHandler entity is designed to be the error handler for everything thrown from within the Endpoint as well as from the entire request handling workflow. So that ResultHandler can examine the kind of error and respond consistently and according to the declared negative response schema. Throwing is not limited to createHttpError(), it can be a class CustomError extends Error {} having your own well-typed properties if needed for the further examination and determination by using instanceof.

[HenriJ]

Sorry, I was not very clear regarding my question about the errors.
My question was if it is possible to trigger a non-2xx response without throwing an exception.

For example returning a 404 if trying to access a non-existing resource is not an "error" (and by that I mean it is not exceptional) and it feels weird to me to throw an exception to model this case.

[RobinTail]

if it is possible to trigger a non-2xx response without throwing an exception.

Yes, @HenriJ, you can make a custom ResultHandler instance that behaves the desired way, based on other criteria, such as even on the output data itself.

404 if trying to access a non-existing resource is not an "error"
it feels weird to me

I refuse to debate on that topic.

[HenriJ]

Thank you very much for all your explanations @RobinTail .

In the end, I followed your advice regarding the use of custom error classes to handle cases like failed authentication or missing resources Since authentication and resource loading are often handled in middlewares, it seems throwing an error is indeed the only way for a middleware to stop the execution of a request—unless there's an alternative I might have missed?

As for the "debate," I sincerely hope I didn’t come across as provocative. My question was asked with genuine curiosity, as I’m truly interested in your perspective as the creator of this excellent framework. Thank you again for the time and effort you dedicate to this project

[RobinTail]

But maybe there can be another variant that does not combine all positive/negative responses, describing each depending on the associated status code instead. That could ease making such a client that involves the status code as the discriminator between the payloads.

interface EndpointNegativeResponse {
  401: { authMessage: string },
  500: { internalMessage: string },
};

However, I'd personally don't go that way, because to me it feels like an assumption.
Instead of relying on the idea that status code 401 comes with a specific payload explicitly different from a one having 500, I'd rather check the payload programmatically — that, in my experience, is better and more reliable, @HenriJ

type EndpointNegativeResponse = { authMessage: string } | { internalMessage: string };

if ("authMessage" in payload) {
  // that's for 401
}
if ("internalMessage" in payload) {
  // that's for 500
}

[RobinTail]

Made it in #2226 , @HenriJ

Should this interface help you to build a status code based client?
Please let me know

[HenriJ]

That looks great. Is it possible in the ResultHandler to specify different schema depending on the status code though ?

My use case would be something like:

• A schema for 2xx (the returned resource for example)
• A specific schema with status for 401 & 403 (is my token invalid ? expired ?)
• General purpose error message for 5xx

[RobinTail]

Is it possible in the ResultHandler to specify different schema depending on the status code though ?

Yes, @HenriJ :

express-zod-api/example/factories.ts

Line 65 in 63ea6e9

export const statusDependingFactory = new EndpointsFactory({

both positive and negative options of ResultHandler can be arrays or functions returning an array of objects describing the possible responses.

[RobinTail]

@HenriJ , EncodedResponse released in v21.7.0 🚀
I hope it will help you to implement a status code depending client for your API.