http: Diagnostic instead of reason codes Q

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.

Thanks!
    Toerless

Received on Wednesday, 6 September 2023 15:42:01 UTC