How to Decide How Many HTTP Status Codes Your API Needs

Over on the Dropbox Developer Blog, Steve Marx takes a look at how many status codes an API should have. APIs make use of standard HTTP status codes, but as Marx points out, there are some factors that could affect the number of codes that should be used. In specific, Marx highlighted the differences between API clients and web browsers, as well as the intended audience, as aspects to consider when deciding on an HTTP status code strategy.

Originally part of the HTTP 0.9 spec defined by Tim Berners-Lee, HTTP status codes are the standard response codes used in any client-server communication. For decades, web browsers have used these codes to automatically take the correct action when talking to a web server.

Much like web browsers, API clients are generic and understand the common HTTP status codes. On the other hand, APIs can have very specific errors that, while understood by an API-specific Library, cannot be understood by a generic API client. The Twilio error 21610 is an example. For these errors, an API provider will often pick a status code and then describe the details of the error within the response body.

One should also consider the API developer’s ability to easily understand an API. Providing status codes that follow convention can help make the API easier to learn, but that should be balanced with the need for specific status codes based on the types of errors encountered.

Marx’s recommendation is to follow a pragmatic approach where an API starts with the status codes 200(OK), 400(Bad Request), and 500(Internal Server Error). From there, you should add just a few specific, actionable status codes that can still be understood by a generic client. The important thing is to listen to your developer audience and meet their expectations.

Be sure to read the next API Design article: Why You Shouldn't Dismiss Hypermedia in Your API Design

Original Article

How many HTTP status codes should your API use?