This article addresses the importance of establishing an error handling framework, specially exceptions generated by APIs.
API error handling should be part of developer planning and support. During the planning definition phase, the following questions require answers.
- Why is the error needed?
- What action is required because of an error?
- Who is the audience for the error?
- Where should the error display?
- How is the error generated?
Review an example of any significant system or application extended outage and you’ll surmise the outage was a direct result of one or more of the following.
- Not enough documentation
- No information about the cause
- Poor error handling
- Most importantly―a poor error handling framework
Error handling operates at a higher level than architectural application exceptions. An error handling framework acts as a “sanity check” for API developers. A thorough error handling framework defines proper policy and service exceptions that system administrators or developers can act upon to correct.
When I speak of frameworks, I’m speaking about defined sets of basic standards that can be reused. The practice of creating a framework not only applies to code, but to error handling. You may not think of error handling as having a separate framework, but establishing an error handling framework that has laser focus, dedicated attention can reap tremendous rewards in the following ways.
- Maintaining a stable system
- Allowing developers to quickly troubleshoot problems
- Aid extending applications
- Quickly ramp-up new developers
Applications developed upon code foundations, or other applications, depend on diagnostics to determine and promptly resolve problems.
Developers should create application-specific exceptions. Exceptions defined in systems may be specific, but can occur in different places. However, it is helpful to define detailed user-friendly exceptions.
Nested exceptions include the original exception and detailed messages specific to the context of an application.
In developing an exception framework consider generating exceptions only if an application can recover (or partially recover) from the error. If unable to recover from an error, issue a custom exception that encapsulates the original exception (if applicable) and includes a meaningful message.
Only generate custom exceptions for more meaningful error handling. When issuing an exception, provide a meaningful and descriptive message. If possible, include specific values.
A good error handling framework divides errors for easily recognized and appropriate action:
- Policy Errors – based on business rules, which are set to baseline business requirements.
- Service Errors – generated at a network level when a network cannot process the incoming request.
- System Errors – returned from a core system from the underlying network.
- Business Errors – an operation failed because business logic cannot produce a successful response because of passed data.