Writing Bulletproof Apps with API Errorpoints

When you're coding up an integration with an API, do you know what will happen if you get errors? Do you even know what kind of errors you might encounter? What would happen if you hit the rate limit? What if the endpoint times out? So many possibilities, but there's really no way you can test every eventuality - is there?

Good, up-to-date documentation is a must for any API. But even so, it's left up to the application developers to deal with errors, exceptions and edge cases as they occur. Wouldn't it be nice if every API had a suite of error scenarios available to call. This is a rather fabulous suggestion from Andrew Cove:

"Any request to a specific error endpoint should always return the error, exactly as it would appear in a response to a functional endpoint. This seems like an easy way to test how your app behaves for all possible errors."

This pattern already exists in payment gateways. Quite often in the sandbox environments for these services you will have a few different fake credit card numbers to try against their payment acquisition system. One will pass and the rest will fail with varying error codes. This is so you can prepare for the error and handle it safely and neatly.

Wouldn't it be fantastic if all APIs could do this for every conceivable error? These "errorpoints" would serve as a brilliant way to test how your app holds up when the APIs you rely on go wrong - before they do actually go wrong.

Take the Twitter rate limit as a simple example. You can read the docs and try to anticipate the error, but you never know if you've got it right until you actually hit the rate limit in a live trial. If you're doing thorough testing, this means really thrashing the API manually. But if Twitter's API could simulate the error with an errorpoint, then you could test this very easily before your app goes live. What a life-saver that would be!

This could be a tough job for API developers, though, and pretty thankless - after all, you're simulating things you hope will never happen. However, API providers should be pushing for better all-round services as it could mean the difference between winning or losing developer confidence.

Error screen capture via Ben Garney

Be sure to read the next Best Practices article: Metrics for Content APIs: An NPR Case Study


Comments (3)


I usually test errors with an API stub. I run a pseudo-clone of the Twitter API on my server and randomly throw out errors to see if my app handles it well. Of course, this was before OAuth made things complicated to replicate. API Errorpoints seems like a better way to deal with this. Great idea!

Thanks for the shout-out, Simon. This idea has gotten a lot of positive feedback. My company will definitely be incorporating error endpoints when we launch our API. Hopefully other API providers will do the same, to address exactly the issues raised by Tim and Sachin.

I love this suggestion! I use a ton of different social APIs and after I get them into production, I spend an inordinate amount of time on gracefully recovering from error condition on third party APIs. I've had to develop detailed instrumentation just so that I capture the headers and body response of error cases so I can figure out exactly how to decipher an error and handle it appropriately.

If there were more APIs that offered what you were suggesting, I think development would be significantly simplified and improved.

Sounds like a great feature for a service like Mashery to provide as part of their API suite.