Is it good practice to modify the reason phrase of an HTTP response?

Question

HTTP errors have standardized response strings associated to their numeric codes. E.g. 404 "Not Found" or 500 "Internal Server Error". From the RFC it is clear that these strings are not relevant for the recognition of the error (only the numeric code is), but fiddling with e.g. tornado it is clear that the reason is generated automatically from the error code, and the reason parameter in the HTTPError class is present (according to the docs) to use non-standard codes, meaning that you are generally not supposed to use it.

My question is: is it good practice to change the reason string to something more specific for the actual error e.g. "500 Unable to connect to backend database" or "500 Hard disk is on fire", or is this practice discouraged, the error should stay "500 Internal Server Error" and any additional information should be in the payload?

Answer 1

HTTP/1.1

According to the RFC 7230, the current reference for message syntax and routing in HTTP/1.1, the reason phrase exists with the sole purpose of providing a textual description associated with the numeric status code and a client should ignore the reason phrase content. The RFC also states that the reason phrase can be empty.

See the quote below:

3.1.2. Status Line

The first line of a response message is the status-line, consisting of the protocol version, a space (SP), the status code, another space, a possibly empty textual phrase describing the status code, and ending with CRLF.

status-line = HTTP-version SP status-code SP reason-phrase CRLF

[...]

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.

reason-phrase = *( HTAB / SP / VCHAR / obs-text )

Quoting the RFC 7231, the current reference for semantics and content of the HTTP/1.1 protocol:

6.1. Overview of Status Codes

[...] The reason phrases listed here are only recommendations -- they can be replaced by local equivalents without affecting the protocol. [...]

In theory, there's nothing that stops you from changing the reason phrase.

However, the existing reason phrases are really well known and widely adopted. Assuming the client should ignore the reason phrase, I would say it's not correct place to send the error message. Consider using the response payload for it.

HTTP/2

HTTP/2 doesn't support reason phrases at all. See the following quote from the RFC 7540:

8.1.2.4. Response Pseudo-Header Fields

For HTTP/2 responses, a single :status pseudo-header field is defined that carries the HTTP status code field. This pseudo-header field MUST be included in all responses; otherwise, the response is malformed.

HTTP/2 does not define a way to carry the version or reason phrase that is included in an HTTP/1.1 status line.