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