Any technical reason not to use my own HTTP response code TEXT if I develop both server & Client?

Question

Over the years, I have seen quite a few questions on this site along the lines of "can I invent my own HTTP response codes"? Generally asked by those who are developing both the server and client. The responses tend to go towards sticking with standard codes.

If I stick with standard HTTP status code numbers, is there any technical reason not to use custom text in order to differentiate between, let's say, multiple 501 responses?

To reiterate, no client except mine will ever see these values, which are returned by AJAX in repose to authenticated requests.

Answer 1

The “status text” doesn't exist anymore in HTTP/2. There is only the numeric code. So you won't be able to use HTTP/2 (or later versions).

According to section 8.1.2.4 Response Pseudo-Header Fields of RFC 7540, which specifies HTTP/2:

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

Answer 2

While you may control all the clients and servers, you also has a third end you need to be aware of: the intermediates.

The intermediates are web servers, proxies, caches, web application firewall, load balancer, CDN, and other intermediate systems that processes the HTTP message that may stand between your clients and servers. Even if you use end to end encryption and control all the intermediaries used, it's generally easier to integrate new intermediaries into the system when you stick to the standards.

With that said, unless configured otherwise, standard compliant intermediaries normally should only use status code when deciding how to process the message and should have ignored the reason phrase, so in most cases it should be safe to customise the reason phrase. The reason phrase should be reserved to only carry human readable reason that shouldn't affect how the message should be processed.

Some references from RFC 7231 (Section 6.1) (emphasis mine):

The status codes listed below are defined in this specification, Section 4 of [RFC7232], Section 4 of [RFC7233], and Section 3 of [RFC7235]. The reason phrases listed here are only recommendations -- they can be replaced by local equivalents without affecting the protocol.

And from RFC 7230 (Section 3.1.2) (emphasis mine):

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.

---

So what should you do instead if standard HTTP status codes aren't sufficient for you?

Use the status code. HTTP Status code is designed to be extensible. Refer to RFC 7231 Section 6 on how to extend HTTP status code in a way that would remain backwards compatible with clients and intermediaries that doesn't understand the extended status code.

Answer 3

An alternative approach would be to include a response body containing the detailed failure reason, for example in a JSON object. This would be comparable to the customized 404 pages which are often delivered to browsers when a non-existent web page is opened.

For example, if your backend is written in Python using Django, you could implement a middleware function (see https://docs.djangoproject.com/en/3.0/topics/http/middleware/) to catch exceptions and return a 500 error with some error JSON object (note this is completely untested, just use it to get an idea how it could be done):

import sys, traceback
from django.http import JsonResponse

def exception_handling_middleware(get_response):

    def middleware(request):

        try:
            # call inner handler
            return get_response(request)
        except BaseException:
            # if any exception happens, return an error response
            # with a 500 status code
            return JsonResponse(
              {
                "error": str(sys.exc_info()[1]),
                "traceback": traceback.format_exc()
              },
              status=500)

Answer 4

By all means use your own codes as the standard HTTP codes really are not that good, but my advice is to keep them separate for maintenance sake and not to confuse anyone who one day may use your code, so rather than 3 digit codes with a decimal point, go with say 5 digit codes