Writing Good API Status Codes

Error Codes may be the last thing you see from an API - they certainly shouldn’t be the last thing you think about!

For HTTP, status code ranges can be easily summarized, but as you can see the general “buckets” require a lot more detail for them to be useful.

1xx: Hold Please

2xx: Great Success

3xx: Go Away!

4xx: You Screwed Up

5xx: We Screwed Up

Even 2xx codes can be misleading, often reporting success when something has in fact gone wrong. Sometimes the error is reported within the response payload - and sometimes not at all. So we’re on a mission to help API providers take their status handling more seriously, and ensure developers get the information they need for their applications.

Understanding Status Codes

Status codes are extremely useful. They are the first opportunity - often synchronously after a request - where a server can inform the client that something went wrong. So let’s look more closely at the HTTP Status Code ranges, and some of the common responses users should expect to deal with, since these dominate Web API integration, and you’ll even find vendor-specific codes in this range:

1xx: Hold Please

The 1xx range has two general functions. The first is for information related to state of the connection - such as 101 Switching Protocols. 1xx also clarifies the state of the initial request. 100 Continue, for instance, notes that a server has received request headers from a client, and that the server is awaiting the request body. 

2xx: Great Success

The 2xx range is reserved for success responses. 200 OK means a request was successful, 201 Created confirms that a request has been fulfilled and a new resource has been created for the client, and 202 Accepted means that the request has been accepted.

3xx: Go Away!

The 3xx range relates to status of the resource or endpoint and indicates the client must take additional action to complete the request. For example, 301 Moved Permanently redirects the  client to a different URI for that request.

4xx: You Screwed Up

The 4xx range includes the ever popular and much parodied 404 Not Found. However, there are other status codes useful for APIs in this range too - such as 429 Too many Requests, used to notify a client that requests have reached a rate limited and are being rejected.

5xx: We Screwed Up

The 5xx range is reserved for status codes related to the server. Unlike 4xx, where the error is the client’s responsibility, 5xx reports when the server has failed for some reason. Unfortunately these aren’t very specific and detail oriented - reporting general failures such as 503 Service Unavailable.

What Makes a Good Status Code

Quality status codes not only communicate what happened, but why it happened. Good status codes must pass three basic criteria in order to truly be helpful:

1. An HTTP Status Code, to show the source and category of the problem.
2. A service specific ID code for more detailed status or error description.
3. A human readable message that summarizes the context, cause, and any solution.

Include Standardized Status Codes

By using a default status, you are providing a good starting point for diagnosis. The 4xx or 5xx range allows the client to know the source of the error. 

Provide Detail

First and foremost, an error code must provide detail. 400 Bad Request means nothing. Passing this information in the body of the response allows service specific errors to be categorized with far greater detail.

Human Context

While machine-readable status codes are key, it’s also important to provide human-readable context. With this context not only do you get the status code, you also get useful, actionable information.

Conclusion 

Best practice is important, yet status codes are often subjective. How you reference links, what error code you generate, and how to display those codes is subject to change from one service provider to another. However, there has been headway to standardize these approaches; the IETF recently published RFC 7807, which outlines how to use a JSON object as a way to model problem details within HTTP response. The idea is that by providing more specific machine-readable messages with an error response, the API clients can react to errors more effectively.

In general, the goal with status responses is to create a source of information to not only inform the user of a problem, but of the solution to that problem as well. This is fundamental to improving the developer experience and delivering a usable, functional API service.