1.12 Error HandlingApril 15th, 2009 — Marieke Guy
Providing good error handling is essential if you want to give the developers using your API an opportunity to correct their mistake. Error messages should be clear and concise and pitched at the appropriate. Messages such as “Input has failed” are highly unhelpful and unfortunately fairly common. Avoid:
- Inconsistency (e.g. different variable order in similar methods)
- Over-general error reporting (a single exception object covering a number of very different possible errors)
- Over-complicated request payload – having to send a complex session object as part of each Web service call.
Log API traffic with as much context as possible to deal with resolution of errors.
Provide permanently addressable status and changelog pages for your API; if the service or API goes down for any reason, these two pages must still be visible, preferably with why things are down.