This week I did a talk about API error handling within CA APIM OAuth Toolkit (OTK). For that I have created a list of general requirements that are important when dealing with APIs. I decided to share that list here since it may be useful for others too.
Here we go:
- The API owner must be in control of error messages. This sounds like a given but especially when choosing a middleware product it should be evaluated if internal errors may be returned instead of ones created by the API owner/developer. That is not desired
- APIs should return correct error messages. This is another one that should be a given. However, if this is not the case developers will be very confused
- Error messages should not reveal sensitive information. The error message should not expose implementation details such as stacktraces. Error messages should be as general and as specific as possible at the same time. For example, returning "authentication failed due to invalid credentials" is general but also specific enough. It would be wrong to return "authentication failed due to the incorrect password 'xyz'"
- Error messages should be returned in an expected message format. If the API consumes and produces JSON messages error messages should also be returned in JSON
- Error messages should be maintained in a single location. This may be controversial and depends on the API development environment. But if many APIs have to be managed a system that has a central location for maintaining error messages may be used. Otherwise, if the error messages are formulated within those APIs directly, it may be difficult to change or fix them
- Same errors should always cause the same error message. If an API implements parameter validation and fails, the produced error message should be the same across all APIs that implement the same validation. This should be consistent for all types of errors
- All possible error responses should be documented. Do not let your API consumers guess what errors may occur. Document all possible errors that may be returned. This includes potential reasons for a failed request and also solutions how this can be fixed. For example, if the error says "token is invalid" you may want to document "the given access_token has expired. Repeat the request using a valid access_token"
Financial API (OpenID Foundation - FAPI)
FAPI is still in an early draft but has documented an approach for handling errors. It may be worth taking a look at it:
As usual please leave a comment with any questions or ideas or different views on this topic if you like.