Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Hints and Tricks for Better API Error Codes

DZone's Guide to

Hints and Tricks for Better API Error Codes

Using well-defined standards and having user experience in mind are what will help you ensure your API is a good one.

· Integration Zone
Free Resource

Share, secure, distribute, control, and monetize your APIs with the platform built with performance, time-to-value, and growth in mind. Free 90-day trial of 3Scale by Red Hat

API development recently has become one of the most attractive and competitive niches of web development. Because there are different technologies to create APIs, there is no one standard or method for designing APIs. However, one of the main objectives for API designers is to build intuitive APIs that would be easy to work with.

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 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.

When you dive deeply, there are only 3 outcomes in the interaction between an app and an API. Among them 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). 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.

    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"
    }

    This is not a bad error format, but it is a bit hard to use. Below is a more evident way an error can be presented to users.

    {
                   "http_code": "401",
                   "message" : "Authentication needed",
                   "internal_error_code" : "128",
                   "details_url" : http:// example.com/errors/128
    }

    We hope that the tips provided in this article will come in handy. Using well-defined standards and having user experience in mind are what will help you ensure your API is a good one.

    Explore the core elements of owning an API strategy and best practices for effective API programs. Download the API Owner's Manual, brought to you by 3Scale by Red Hat

    Topics:
    api best practices ,api development ,api design

    Published at DZone with permission of Andriy Pontus. See the original article here.

    Opinions expressed by DZone contributors are their own.

    THE DZONE NEWSLETTER

    Dev Resources & Solutions Straight to Your Inbox

    Thanks for subscribing!

    Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

    X

    {{ parent.title || parent.header.title}}

    {{ parent.tldr }}

    {{ parent.urlSource.name }}