Status and error codes are a number in the response header that indicates the general classification of the response – for example, whether the request was successful (200), resulted in a server error (500), had authorization problems (403), and so on. Standard status codes usually don’t require much documentation, but custom API-specific status and error codes are needed. Error codes, in particular, are helpful in troubleshooting faulty requests.
Where to list HTTP response and error codes
It is more practical for APIs to have one page with responses and error codes to the entire API. A separate page listing the status codes (instead of adding a status code to each endpoint) allows for more detail on each code without overcrowding other parts of the documentation. This approach reduces redundancy and the feeling of information overload.
On the other hand, if some state and error codes are more appropriate for certain endpoints than others, it makes sense to display such state and error codes on the endpoint description pages.
Such a strategy might be to call attention to any particularly important status or error codes for a particular endpoint, and then go to the centralized Response and Status Codes page for complete information.
Where to get error codes and statuses
Status and error codes may not be obvious in the API documentation. You will probably have to ask developers to provide a list of all status and error codes that are unique to the API. Sometimes developers hardcode the status and error codes directly into program code, and they don’t have easy ways to pass the full list (which also makes localization difficult).
As a result, it may require a tambourine dance to find all the codes. In particular, you may have to break the API to see all possible error codes. For example, if you exceed the rate limit for a particular request, the API may return a special error or status code. Such custom code should definitely be documented. In the API troubleshooting section, you can specifically post examples of how to retrieve error codes.
Status and error codes are helpful in troubleshooting problems
Status and error codes are particularly useful in troubleshooting. Thus, you can consider error codes as a supplement to the troubleshooting section.
Each part of the documentation can be useful in the troubleshooting section. The troubleshooting section can describe what happens when users go off the beaten path and stumble into the dark forest. Status codes are like clues to help users get back on the right path.
In the troubleshooting section, you can list error messages related to the following situations:
- using invalid API keys;
- use of invalid API keys;
- parameters do not match data types;
- API throws an exception;
- no data to return the resource;
- rate limit exceeded;
- parameters are outside the acceptable maximum and minimum limits;
- a mandatory parameter is missing from an endpoint.
- the error text must be accurately documented so that it appears easily in a search.