When you're using an API, errors are unfortunately inevitable. Whether you've forgotten to pass in a required property, sent an expired API key or a completely unexpected and out of your control server error.
What happens next completely depends on the API you're using—there's no real standard for APIs to return if there's an error. You may see one or more of the following:
- appropriate HTTP status code/message
- error code as response header
- error code in response body
Depending on the API what you do next can vary wildly. If you're lucky it'll have good documentation for each of these errors. If you're unlucky then you'll have to scrabble around trying different encodings, params and URLs to hope the error goes away.
A new approach
Just before the holidays we deployed a brand new doc type to ReadMe: API Error.
This is a new first-class doc type in ReadMe with the sole purpose of allowing you to document all of the different error cases that your API may produce. You have to provide us with an Error Code, then after that it's a regular ReadMe doc.
This Error Code can be used to link to your docs page using the new top level /error URL. Any error doc can be accessed by going to /error/${errorCode}. E.g. if you have a code of ERROR_CODE and your docs site is at https://docs.example.com you can access that error doc by going to https://docs.example.com/error/ERROR_CODE. This will redirect to the appropriate slug to render the doc.
We're encouraging you to use this URL in your API responses so when inevitably errors do occur, your users can jump straight into your docs to debug.
If you want to see how this combines with our API Metrics product, see this follow up post.