A Primer for HTTP Status Codes

Web traffic follows a fairly standard flow. Request to Response. Someone makes a request to a server (e.g., your mobile phone makes a request to Twitter’s server), and the server then processes that request and sends a response. All responses include a status code. The most common status code people see is 404 (and websites have gotten pretty clever with their responses). Status codes belong to one of five groups:
  • 100 – 199 = Information
  • 200 – 299 = Success
  • 300 – 399 = Redirection
  • 400 – 499 = Client Error
  • 500 – 599 = Server Error
You may see these referred to as 1xx, 2xx, 3xx, etc. to denote the ranges. A server error (5xx) may happen when an application says “Hey, the code crashed and I cannot recover. Return a 500 (Internal Server Error).
User-facing web apps typically have a custom error page. Remember those clever 404 pages linked above? That’s simply a custom error page on the 404 status code. The flow goes like:
  • The application code raises an error.
  • The application then creates a response with a 500 status code.
  • The server the is running the application intercepts the 500 response, and instead returns a “more user-friendly” error page (such as these).
  • The user actually gets back a valid HTML page informing them an error occurred.
  • Plot Twist: The status code for the HTML error page is actually 200 (“success”). Although there was an error, the server intercepted the “error” response and returned a friendly HTML page. Because that HTML page was returned successfully, the status code is 200.

The trick with web APIs

A RESTful web API is expected to use meaningful error codes. In other words, instead of sending a friendly response of “Whoops, some error occurred”, an API should use a status code to indicate what happened. Remember that APIs are meant to be called programmatically, and a friendly error page only obfuscates what happened. For example,
  • [GET] api/users/some-non-existent-user should return a 404 (not found)
  • [POST] api/users/some-existing-user should return a 409 (conflict)

Check out the fantastic list over at https://www.restapitutorial.com/httpstatuscodes.html for more details.

Your Thoughts?

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s