HTTP status codes to handle errors in your API

Category: Misc
HTTP status codes to handle errors in your API

Recently I’ve been exploring the guides on how to develop API’s the correct way. The API that I’m planning to build in fact will be used only by me but when starting to build something from a scratch it’s always a good practice to implement it in the generally accepted way. After some research and planning I reached the errors part.

How should you handle errors in your API? The best way to handle them are HTTP Status Codes. For some developers HTTP Status Code might sound very intimidating but in fact they are very easy to understand.

When a browser sends a request to a server, it responds back with HTTP status codes, three digits long.

There are over 70 HTTP status codes. However, most developers don't have all 70 memorized. So most of the developers have to head over to Wikipedia to figure out what a certain Status Code is trying to tell them.

The easiest way to memorize Status Codes in general is to differentiate them with the first digit out of three. When you take a closer look you’ll understand that those codes fall into 5 classes or types. These are 1xx, 2xx, 3xx, 4xx and 5xx classes.

1xx - Informational - Request received, continuing process. This class of status code indicates a provisional response, consisting only of the Status-Line and optional headers, and is terminated by an empty line.

2xx – Success - This class of status codes indicates the action requested by the client was received, understood, accepted and processed successfully.

3xx – Redirection - This class of status code indicates that further action needs to be taken by the user agent in order to fulfil the request. The action required may be carried out by the user agent without interaction with the user if and only if the method used in the second request is GET or HEAD. A user agent should not automatically redirect a request more than five times, since such redirections usually indicate an infinite loop.

4xx - Client Error - The 4xx class of status code is intended for cases in which the client seems to have erred. Except when responding to a HEAD request, the server should include an entity containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method. User agents should display any included entity to the user.

5xx - Server Error - Response status codes beginning with the digit "5" indicate cases in which the server is aware that it has encountered an error or is otherwise incapable of performing the request. Except when responding to a HEAD request, the server should include an entity containing an explanation of the error situation, and indicate whether it is a temporary or permanent condition. Likewise, user agents should display any included entity to the user. These response codes are applicable to any request method.

HTTP Status Codes come in handy when developing your own API’s. It easier for everyone to understand generally accepted status codes than reading your boring documentation about new status codes that you have created for you API.

A very useful article by Brian Mulloy – “RESTful API Design: what about errors?” suggests that you should follow these major classes of HTTP Status Codes rather than creating your own.

From the perspective of the developer consuming your Web API, everything at the other side of that interface is a black box. Errors therefore become a key tool providing context and visibility into how to use an API.

This is why you should use generally accepted HTTP status codes and the best practice is to even narrow them down to several “most API providers use a small subset. For example, the Google GData API uses only 10 status codes, Netflix uses 9, and Digg, only 8” – suggests Brian Mulloy, Apigee.com.

When you boil it down, there are really only 3 outcomes in the interaction between an app and an API:

  • Everything worked
  • The application did something wrong
  • The API did something wrong

Start by using the following 3 codes. If you need more, add them. But you shouldn't go beyond 8.

  • 200 - OK
  • 404 - Not Found
  • 500 - Internal Server Error

If you're not comfortable reducing all your error conditions to these 3, try picking among these additional 5:

  • 201 - Created
  • 304 - Not Modified
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 – Forbidden

To see the full list of HTTP Status Codes visit Wikipedia or check out restapitutorial.com.

This article was inspired by HTTP Status Codes in 60 Seconds from “...in 60 Seconds” series by Tutsplus.