Documenting status and error codes

Status and error codes show a code number in the response header that indicates the general classification of the response — for example, whether the request was successful (200), resulted in an server error (500), had authorization issues (403), and so on.

Standard status codes don’t need documentation as much as custom status and error codes specific to the API. Error codes in particular help with troubleshooting bad requests.

Example of status and error codes

Here’s an example of a status and error codes section in Flickr’s API:

Here you can see that mostly the status and error codes are not the standard codes common to all requests (like 200), but are rather codes that are specific to Flickr’s API.

Here’s an example from OpenSecret’s API:

Open Secrets API status and error codes

Honestly, I’ve never seen so many status and error codes listed. But I think it’s great to document this information if it’s relevant to the API. (Obviously, if users would rarely encounter a particular status code, don’t include it.)

The status and error codes section of an API is often the same across most resources. As a result, this section might appear outside the reference topics. But as a convenience, the status and error codes are often embedded in each reference topic as well, with the assumption that developers need quick access to these codes as they’re working with the endpoints.

In the Clearbit API, the error codes appears as its own topic:

Clearbit status error codes

Again, although many codes are standard, some unique codes specific to the Clearbit API are highlighted, such as 402: “Over plan quota on this endpoint.”

Finally, here’s an example of status and error codes from Dropbox’s API:

Dropbox API example with errors

Sample status code in curl header

Status codes don’t appear in the response body. They appear in the response header, which you might not see by default.

Remember when we submitted the curl call back in an earlier lesson? In one exercise, we submitted a curl call and specified (by adding --include or -i) that we wanted the response headers included in the response:

  curl --get -include 'https://simple-weather.p.mashape.com/weather?lat=37.354108&lng=-121.955236' \-H 'X-Mashape-Key: APIKEY' \
  -H 'Accept: text/plain'

The response, including the header, looked like this:

HTTP/1.1 200 OK
Content-Type: text/plain
Date: Fri, 16 Jun 2017 21:48:55 GMT
Server: Mashape/5.0.6
Via: 1.1 vegur
X-Powered-By: Express
Content-Length: 41
Connection: keep-alive

30 c, Sunny at Santa Clara, United States

The first line, HTTP/1.1 200 OK, tells us the status of the request. (If you change the method, you’ll get back a different status code.)

With a GET request, it’s pretty easy to tell if the request is successful because you get back the expected response.

But suppose you’re making a POST, PUT, or DELETE call, where you’re changing data contained in the resource. How do you know if the request was successfully processed and received by the API? HTTP response codes in the header of the response will indicate whether the operation was successful. The HTTP status codes are just abbreviations for longer messages.

Common status codes follow standard protocols

Most REST APIs follow a standard protocol for response headers. For example, 200 isn’t just an arbitrary code decided upon by the Mashape Weather API developers. 200 is a universally accepted code for a successful HTTP request.

You can see a list of common REST API status codes here and a general list of HTTP status codes here. Although it’s probably good to include a few standard status codes, comprehensively documenting all standard status codes, especially if rarely triggered by your API, is unnecessary.

Where to list the HTTP response and error codes

Most APIs should have a general page listing response and error codes across the entire API. In addition to the Clearbit example mentioned above, Twitter’s API also has a good example of the possible status and error codes you will receive when making requests:

Twitter API status codes

This Response Codes page stands alone rather than appearing embedded within each API reference topic. However, either location has merits. A standalone page allows you to expand on each code with more detail without crowding out the other documentation. It also reduces redundancy and the appearance of a heavy amount of information (information which is actually just repeated).

On the other hand, if some resources are prone to triggering certain status and error codes more than others, it makes sense to highlight those status and error codes on the relevant API reference pages. Perhaps you could call attention to any particularly relevant status or error codes, and then link to the centralized page for full information.

Where to get status and error codes

Status and error codes may not be readily apparent when you’re documenting your API. You will need to ask developers for a list of all the status and error codes that are unique to your API. Sometimes developers hard-code these status and error codes directly in the programming code and don’t have easy ways to hand you a comprehensive list (this makes localization problematic as well).

As a result, you may need to experiment a bit to ferret out all the codes. Specifically, you might need to try to break the API to see all the potential error codes.

For example, if you exceed the rate limit for a specific call, the API might return a special error or status code. You would especially need to document this custom code. A troubleshooting section in your API might make special use of the error codes.

How to list status codes

Your list of status codes can be done in a basic table or definition list, somewhat like this:

Status code Meaning
200 Successful request and response.
400 Malformed parameters or other bad request.

Status codes aren’t readily visible

Status codes are pretty subtle, but when a developer is working with an API, these codes may be the only “interface” the developer has. If you can control the messages the developer sees, it can be a huge win. All too often, status codes are uninformative, poorly written, and communicate little or no helpful information to the user to overcome the error.

Status/error codes can assist in troubleshooting

Status and error codes can be particularly helpful when it comes to troubleshooting. Therefore, you can think of these error codes as complementary to a section on troubleshooting.

Almost every set of documentation could benefit from a section on troubleshooting. Document what happens when users get off the happy path and start stumbling around in the dark forest.

A section on troubleshooting could list possible error messages users get when they do any of the following:

  • The wrong API keys are used
  • Invalid API keys are used
  • The parameters don’t fit the data types
  • The API throws an exception
  • There’s no data for the resource to return
  • The rate limits have been exceeded
  • The parameters are outside the max and min boundaries of what’s acceptable
  • A required parameter is absent from the endpoint

Where possible, document the exact text of the error in the documentation so that it easily surfaces in searches.

37% Complete

37/92 pages complete. Only 55 more pages to go...

Contribute?

If you would like to contribute back to say thank you for the API documentation course, click the Donate button below. Alternatively, to contribute content, such as a tutorial or a new section, contact me with your ideas. You can also submit a pull request in the GitHub repo to make your contribution. Even if you want to just fix a typo or add a sentence here and there, it's always welcome.

Get new posts delivered straight to your inbox.

Subscriber count: 4,285