In one study which analyzed 922 Amazon EC2 API call issues, 19% of the cases were related to the output issues of API calls, including failed calls with unclear error messages, as well as missing output, wrong output, and unexpected output of API calls. (“Cloud API Issues: an Empirical Study and Impact”). In these cases 61% of the users understood the problem from the error message but did not know the solutions to the problem while 39% of the users did not understand what caused the problems or to fix them. That should give you some indication of the importance of proper error messages.

First of all: With REST APIs, use HTTP status codes! but don’t overuse them. There’s like 70 of them. Most API providers use a small subset. For example,the Google GData API uses only 10 status codes; Netflix uses 9, and Digg, only 8. Otherwise great API can become hated due to obscure error messages. MrMurphy will make a visit to your house as well.

Every API will fail occasionally and thus error messages must be good. Dispite of your excellent API documentation, developers might try to use your API with false options. Again, error messages to the rescue.

When you boil it down, there are really only 3 outcomes in the interaction between an app and an API:

Normally if everything goes fine, the response code 200 is returned in headers. There are differences though. According to some sources for example Facebook responds always 200 dispite something went “wrong”. I would not know about that. I’ve never used Facebook APIs.

That is not appreciated by some developers.

Bad error messages waste everyone’s time

According to Nordic APIs, a quality error code should include:

Then what is a good error message?

Twitter does a pretty good response:

> GET /1.1/statuses/mentions_timeline.json HTTP/2
> Host:
> User-Agent: curl/7.54.0
> Accept: */*
* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
< HTTP/2 400 
< content-length: 62
< content-type: application/json; charset=utf-8
< date: Wed, 07 Aug 2019 17:31:01 GMT
< server: tsa_o
< set-cookie: personalization_id="v1_RmghO3ihXqURR2OgTQveFw=="; Max-Age=63072000; Expires=Fri, 6 Aug 2021 17:31:01 GMT; Path=/;
< set-cookie: guest_id=v1%3A156519906164056735; Max-Age=63072000; Expires=Fri, 6 Aug 2021 17:31:01 GMT; Path=/;
< strict-transport-security: max-age=631138519
< x-connection-hash: 64a3453098de87fc57cba4165eeb741e
< x-response-time: 115
* Connection #0 to host left intact
{"errors":[{"code":215,"message":"Bad Authentication data."}]}

The line HTTP/2 400 tells us that error happened (Bad Request 400). Number 215 in the response body is the internal error code, with which I can use to seek for more information. I would have added there a link to documentation where the authentication is explained or link to error code (which in turn would link me to auth documentation).

I would take it towards this pseudo example:

 "response_code" : 401, 
 "message" : "Verbose, plain language description of the problem with hints about how to fix it.", 
 "more_info" : "", 
 "code" : 12345

In summary, be verbose and use plain language descriptions. Add as many hints as your API team can think of about what’s causing an error. I recommend you to add a link in your description to more information. That is what for example Twilio does.

Make use of the error situations

Of course wise API providers track and analyze the error situations in logs to pinpoint unintended usage of the API. Analyzing the errors you might find patterns and then based on what is learned change the API or iterate the documentation.

Your logs and monitoring in general should naturally alert you when your code is failing too. The latter should not be common if you have done proper testing. Of course current services are often so complex systems that one minor change in one “distant” part might cause unintended changes elsewhere - for example in your API.

Also make sure your API docs is uptodate so that your advises on the usage are not driving consumers towards errors. That is most irritating!

Be alert, analyze and constantly improve your API, documentation and examples.

Some more to read from 100 Days DX