Re: http: Diagnostic instead of reason codes Q

Hi Toerless,



On Wed, Sep 6, 2023 at 4:45 PM Toerless Eckert <tte@cs.fau.de> wrote:

> If i build a REST API via HTTP, and there is a semantic issue with some
> operation, GET/POST. I guess it is NOT appropriate to indicate the specific
> semantic issue in the reason code of the HTTP status line. Especially i
> guess
> it is not appropriate to attempt distinguishing two different semantic
> error
> conditions by returning the same http status code, but two different
> reason codes.
>
> If this is correct:
>
> Where is this logic/rule specified ? I am only deducing it from the fact
> that the reason
> phrase was retired from HTTP 2.0 (and 3.0), but its still mentioned in
> rfc9110,
> and there is no explanation as to the reason of its retirement.
>
> What would be the recommended way to signal back such semantic REST api
> error conditions,
> that can not/should not be expressed (solely) via HTTP status codes ?
> (i thought someone pointed me to some RFC for this a longer time ago, but
> i can't
>  locate tht thread anymore *sigh*).
>
> Or more generally: Where is the spec that explans to me what error
> conditions are appropriate
> to express via a HTTP status code, and which ones are not. As in: I have
> to review some
> HTTP based API and wonder how to check whether status codes are applied
> correctly.
>
>
Casting an eye back to RFC 7230, it stated in Section 3.1.2

> a possibly empty textual phrase describing the status code

and

>    The reason-phrase element exists for the sole purpose of providing a
   textual description associated with the numeric status code, mostly
   out of deference to earlier Internet application protocols that were
   more frequently used with interactive text clients.  A client SHOULD
   ignore the reason-phrase content.

Given how wooly the phrase has been defined/used, especially where
intermediaries are in the mix, depending on it for applications is not a
great idea. As you note, H2 and H3 can't even carry the phrase but H1.1
proxies can and do rewrite phrases as they see fit too. I've seen this
manifest first hand when debugging an application that worked directly but
failed when proxied. RFC 9205 has some pretty clear guidance on reason
phrases in section 4.6[1]

> Applications using HTTP MUST NOT re-specify the semantics of HTTP status
codes, even if it is only by copying their definition. It is NOT RECOMMENDED
they require specific reason phrases to be used; the reason phrase has no
function in HTTP, is not guaranteed to be preserved by implementations, and
is not carried at all in the HTTP/2 [HTTP/2
<https://www.rfc-editor.org/rfc/rfc9205#HTTP2>] message format.

and earlier on in the section it suggests you can use "problem details".
The latest version of that is RFC 9457 [2]

> To distinguish between multiple error conditions that are mapped to the
same status code and to avoid the misattribution issue outlined above,
applications using HTTP should convey finer-grained error information in
the response's message content and/or header fields. [PROBLEM-DETAILS]
provides one way to do so.

Hope that helps clarify a few things.

Cheers
Lucas

[1] https://www.rfc-editor.org/rfc/rfc9205#section-4.6
[2] https://www.rfc-editor.org/rfc/rfc9457.html