Error handling is not what most software developers like to think about, but it is a very important issue especially for those who are designing an API. The problem that occurs for developers when they are writing the code that deals with an API is that they need to convert these errors into intelligible messages for their apps.
Different APIs are based on different technologies and libraries that’s why error codes are often duplicated and not recognizable for the particular framework used by the consumer. It’s even worse when the error code that must be handled by the application passes through it without any treatment and reaches end-users that don’t have a clue about it.
Making sure your API error codes are clear for its consumers does not take much inventing. If you’re providing a REST API, users expect that your endpoints are similar to any other HTTP endpoint. Thus, it would be great if you simply pursue the standards.
A Few Tips to Better API Error Codes
The first tip is to use general HTTP status codes. There are over 70 of them, but most developers don't have all them memorized. If you choose the status codes that are not very common, they will have to surf the web in search of what you are trying to tell them. That is why most API providers use a small set that in average contains from 8 to 10 status codes.
There are only 3 outcomes in the interaction between an app and an API. Among them, the protocol defines two main classes of error codes:
- The application did something wrong - codes starting with 4 (e.g. 400, 401, 403). They are intended for cases in which the client have erred, and the payload should present a solution to the problem.
- The API did something wrong -codes starting with 5 (e.g. 500, 503, 504). They indicate cases when the server does not handle the call right, and the payload should provide details on whether it is temporary or permanent.
In both cases, the HTTP protocol defines that servers “should include an entity containing an explanation of the error situation, and indicate whether it is a temporary or permanent condition”.
However, there are some cases where a specific API error cannot be described by common HTTP status codes. Then you should simply throw error details in the payload and use the general HTTP 400 or 500 error codes. The payload format can be JSON or XML. Which one to choose depends on what MIME (Multipurpose Internet Mail Extensions) type your API uses.
Another hint that worth to be mentioned is not to reply with 404 to all calls to non-existent API endpoints that correspond to missing methods. Why? Because it will send the general “Not Found” HTML page back to the caller which doesn’t make sense if there’s not a human on the other side of the line. In such situations, it would be better to reply with 404 but using a body that your caller can understand (JSON or XML). The even better solution is to reply with a 501 (Not Implemented) if the method is not implemented. If it’s executed but not available for a specific resource, it would be great to reply with a 405 (Method Not Allowed), indicating that the request method is not allowed for the requested resource.
What About Error Format?
Choosing the correct error format that would be completely understandable for API users is very important if you intend to make the API you are working on an excellent one. Let’s consider one of the existing types of error format:
{
"error_type": "Application Error",
"error_details": "#500: Internal server error"
}
It is not a bad error format, but it is a bit hard to use. Below is a more evident to users way an error can be presented.
{
"http_code": "401",
"message" : "Authentication needed",
"internal_error_code" : "128",
"details_url" : https:// example.com/errors/128
}
Conclusion
We hope that the tips provided in the article will come you in handy. Using well-defined standards and having user experience in mind are what will help you ensure your API is a good one.
