HTTP APIs and errors – doing it the right way

Errors are the third class citizen of any interface; nobody wants to deal with them. Not enough care goes to crafting proper errors, but this is a mistake. It’s when things break your API consumers need most help. Proper error handling distinguishes good APIs from great. If you follow the recommendations outlined in this blog-post, you’ll be one important step closer to having a great API.

The basics

Since we’re dealing with HTTP here, be sure to take advantage of it. Always respond with a 4xx or 5xx status code when an error occurs. If you’re sending 200 OK, you’re doing it wrong. Make sure the payload is of the same content type as the rest of your API, whether you’re using JSON, XML, HTML or any other format, otherwise you’ll create a headache for API consumers. Be sure you send the appropriate Content-Type header (optionally respecting the Accept header). Most of this is covered in this great training video from Layer7.

Error payload

A title, description and an error code is the bare minimum you should send. The title and description are components of the error message which I write about in the next section.

As mentioned earlier, HTTP already provides us with a set of error codes and for simpler APIs, these work great and are sufficient. If you need more granular reporting, add another field to the payload which holds an application-specific error code. Have a document online with a detailed description of every application error code and add a URL pointing to it to the error payload (h/t to John Sheehan for bringing this out in the comments) This greatly helps when debugging less obvious error states.

Hence, a good error coming from an HTTP API might be similar to this:

Anatomy of a good error message

A good error message should be as specific as possible. Don’t use general terms as “Something went wrong” or “Error occurred”. That’s obvious. An error message should help the user recover from it. Provide hints to what went wrong, if something is missing, not well formed or conflicting. You’ll get bonus points for giving instructions on how to actually fix the error.

Also, keep in mind who’s the intended audience. Most API errors will be seen by developers, so you can “talk” to them in more technical terms. Some, however, may bubble up to regular app users, keep that in mind. In this case, send the title and description localized, according to the Accept-Language header.

Finally, don’t be afraid to write the error message in a human way, it will appear less frightening. UPDATE: Check out this great answer on StackExchange.


It goes without saying that all errors should be logged. What I found useful is to log the full HTTP request and the application stack trace. Have this log available online and add a new field to the error payload containing a link to the encountered error. The API consumers can then paste this link in their bug report. It makes debugging and cooperation between developers much easier.


Error states are an important part of every interface. Treat them as such, don’t ignore them. Users of your API will praise you.

2 thoughts on “HTTP APIs and errors – doing it the right way

Share your thoughts

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s