Feature Request: Client should return all expected status codes

[TylorS]

At present a Client derived from an API loses all type-safety in regards to any non-2xx status codes which are returned directly when making use of the Client's methods.

The way to recover access errors are via ClientError. The server-side ClientError's, which do have a status, are typed as unknown and must be re-validated manually to ensure type-safety on the client-side by hand.

In an ideal world I think these would be strongly typed by default by using the "success" channel of Effect to return all "expected", as defined by your API, instead of only 2xx status codes. This allows for type-safe transformation of all "expected" status codes into domain-specific values and/or failures to correspond with these other expected conditions.

Prior Discussion: https://github.com/sukovanej/effect-http/pull/515

[sukovanej]

Hey, I agree the error responses are handled poorly right now. The most problematic traits I currently see:

• the missing type-safety and validation on the client side - what you're describing in here
• type safety on the server-side - whatever non-2xx response can be returned from a handler
• missing documentation in the OpenApi - result of the previous point

I'll put there random thoughts and let's elaborate.

On the server side

• I want to be able to automatically translate Effect errors onto non-2xx http responses because the implementation then can make use of the short-circuiting.
• I want to have the ability to fail with whatever arbitrary error that I can handle for the whole http app. Things like database connection failures are good example - I don't want to bother handling these per endpoint.
• Ideally, I want to be forbidden to fail with non-documented errors but this is contradicting the previous one.

On the client side

• Because of the definition of the http statuses, I can decide on which responses are failures (4xx, 5xx) and which are successes (2xx). From experience, I think I always translate non-2xx responses onto failures, and I believe this automatic conversion into effect successes and failures plays well with the level of abstraction this lib is aiming to provide. This view is opposing your idea of representing all defined responses using the Effect success channel, let's dig deeper onto this one.
• With type-safe error responses we still need the ability to represent arbitrary undocumented errors because things can go sideways e.g. in load-balancers on the way to the server.
• Undocumented errors should be expected Effect errors because I still want to be able to trigger retry on the client side when e.g. k8s decides to rotate a node pool and due to no available downstream the load balancer returns 502/503 which is almost never documented in the OpenApi.

[adrian-gierakowski]

@TylorS @sukovanej have you given any further though to this or scheched something out privately? I'm using effect-http in production and not having typed error on the client side is a noticable downgrade compared api-ts (which we are still using on non-effect based projects).

[danielo515]

I am also interested in graceful handling of errors. If I hate something is libraries that throw in non 2xx scenarios