wrong http status code

There’s Something Seriously Wrong with an HTTP Status Code

wrong http status code

I relish writing and communicating general truths on programming strategies that keep our code simple and understandable; you know, all that Software Craftsmanship stuff.


If there is one thing I enjoy even more, it’s sharing little idiosyncracies that have crept into particular programming paradigms. Why? Because it shows we are only human and all of us make mistakes. Programmers have produced incorrect or awkward specifications for some time now. 


For an excellent example, we need to look no further than the misspelt ‘Referer’ HTTP Header, incorporated by a computer scientist into the original specification of the hypertext transport protocol. Mind-blowing fact: Due to the proliferation of the web and the billions of HTTP requests sent out daily, there will have been significantly more recorded instances of the infamously incorrect ‘Referer’ than the proper ‘Referrer’.


Similarly, one of the standard HTTP Status Codes, as Elmo would say ‘is not like the others’. Here, a mere misspelling is not the problem. Instead, we have a case of the wrong meaning.


Which HTTP status code could it be? 


I am referring to the 401 – Unauthorized error response. As a client, this reply indicates a protected resource. We must identify ourselves—authenticate—before we may get access. The complaint from the server is a lack of Authentication; Authorisation doesn’t come into it. What is the difference between the two terms? Authentication confirms a user’s (or service’s) identity, while Authorisation establishes their access privileges.


When a client receives a 401 HTTP status code, it’s a prompt to try again but this time with authentication details. For example, the appropriate web UI reaction to a 401 status code redirects users to a login form to establish their identity.


Wouldn’t 401 – Unauthenticated have been a better name? I certainly think so. This incorrect naming has been confusing the web development community for a long time. I still remember being baffled about the difference between the 401-Unauthorized and 403-Forbidden HTTP status codes—Don’t they mean the same thing??


Many websites and APIs return a 401 – Unauthorized response code when the user is unauthorised. Hold on, isn’t that correct?? An Unauthorized response for an unauthorised client?! 


Unfortunately, that is an incorrect application of the 401 status, even though its very name asserts correct usage. Confusingly, 403 – Forbidden is the proper status when a client is not authorised, i.e. we know their identity, but they need suitable access rights for a particular action. Granted, 403 – Forbidden isn’t the most descriptive name, but at least it indicates a permissions problem.


To recap, when it comes to HTTP response status codes, please remember that 

  • 401 – Unauthorized, means Unauthenticated, i.e. the server doesn’t know who sent the request (their identity) while
  • 403 – Forbidden, we should interpret as Unauthorized, i.e. the client identity is missing the permissions for this action.


Hopefully, this article has clarified some confusion around standard HTTP error status codes.

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply