Re: [httpapi] RFC for HTTP API error responses (was: rfc7807 errata or just "more")

[Darrel Miller <[e-mail]>]

Ben, Sanjay,

From: httpapi <[e-mail]> on behalf of Sanjay Dalal <[e-mail]>
>I find that error responses - and more generally error handling - is severely lacking in many systems I come across, and it's causing problems during software development.

Huge +1. Lack of it, increases cost of support, affects developer experience.

I agree that HTTP errors are often not handled well.  However, usually I find that is because devs over simplify client code to something like:

   if status == 200 then success else throw exception.

I find it is this part of RFC 7231 that most developers don't follow,


   HTTP status codes are extensible.  HTTP clients are not required to
   understand the meaning of all registered status codes, though such
   understanding is obviously desirable.  However, a client MUST
   understand the class of any status code, as indicated by the first
   digit, and treat an unrecognized status code as being equivalent to
   the x00 status code of that class, with the exception that a
   recipient MUST NOT cache a response with an unrecognized status code.

Clients must handle each class of status code, but are not required to handle every specific failure condition.

Is it your expectation that a client must understand all service-specific modes of failure in order to make a request to an HTTP API?

On Fri, Jan 15, 2021 at 8:08 PM Ben Bucksch <[e-mail]<mailto:[e-mail]>> wrote:
I wanted to propose to make a new RFC for nailling down not only the error responses, but also what information is expected in the response, and the behavioral contract. Errors should be part of the protocol and API contract.
Errors are part of the HTTP protocol.  That's what 4XX and 5XX status codes are.  Possible errors can be called out in API descriptions like OpenAPI but in my opinion they should never be relied on to be exhaustive by a client.  The layered nature of HTTP means that any intermediary could return an HTTP error response that is not provided by the OpenAPI description.

Creating a further refinement of HTTP status codes using service specific problem types can be useful as long as clients can opt-in to processing those new error types.

Darrel