Fault handling provides a mechanism for managing exception conditions that arise during message processing on the API Platform. API proxies, like any other application, should be designed it to handle failures gracefully, by returning error messages that assist in root-cause analysis as well as by issuing appropriate notifications and alerts.
To enable fault handling for an API proxy, fault handlers must be configured to identify and categorize predefined exception conditions, in turn enabling the API Platform to execute policies that manage the exception.
The API Platform organizes faults into the following categories and subcategories.
| Category | Subcategory | Fault Name | Description |
|---|---|---|---|
| Messaging | Failures that occur during the message flow (not including policy failures) | ||
| Custom faults | {fault_name} | Any faults deliberately raised by the API facade using the Raise Fault policy | |
| Response codes | InternalServerError, NotFound | HTTP error codes 5xx, 4xx | |
| Routing failures | NoRoutesMatched | Failure in selecting a named TargetEndpoint for a request | |
| Classification failures | NotFound | Failures caused by a request URI that does not match any basepath for any ProxyEndpoint configurations | |
| Transport | HTTP transport-level errors | ||
| Connectivity | ConnectionRefused, ConnectionReset, ConnectionTimeout | Failures occur while establishing network or transport-level connections | |
| Request validations | ContentLengthMissing, HostHeaderMissing | Faults occur during semantics checks on every request | |
| Response validations | Faults occur during semantics checks on every response | ||
| IO errors | SSLHandshakeError, ReadTimeout, ReadError, WriteTimeout, WriteError, ChunkError | Read/write errors at client or target endpoints, timeouts, SSL errors, and chunked errors | |
| System | Undefined runtime errors | ||
| Memory | OutOfMemory, GCOverLimit | Memory-related failures can be considered faults | |
| Thread | RogueTaskTerminated | Failures such as termination of run-away tasks | |
| Policy | Policy enforcement failures | ||
| RateLimitFailure | QuotaLimitExceeded, MessageWeightUnresolved | Failures such as exceeded quota rate or unresolved message weight are defined as faults | |
| ScriptEvaluationFailure | ScriptEngineFailure | Script execution failures caused by JavaScript or Python policies | |
A fault is always accompanied by a text description of the reason for the failure. When the system raises a fult, a set of attributes are populated to assist in troubleshooting. A fault includes the following information:
- Reason
- User-defined custom attributes
When a fault occurs, the messaging framework categorizes the fault into the application, transport, or system categories, and also determines the subcategory. When a policy is added, the framework declares all the subcategories of errors.
Note: Policies can define one or more fault handlers to deal with specific status or error codes. For example, an authentication policy can contain a fault handler to define the action to take when a password expires or a login fails.
Fault handling flow
When a fault occurs in a message flow, the fault handler employs the following fault rule to match the fault with a fault handler:
- An optional condition that catches the fault category, subcategory, name, or attributes
- A list of policy attachments that express the necessary processing
You can apply multiple fault rules to either the proxy or target in a flow. Only the first fault rule that matches the fault type, or whose condition evaluates to true, is enforced. Fault rules are evaluated and enforced in the following order:
- Request path:
- Fault in proxy request: Fault rules defined at ProxyEndpoint.
- Fault in routing: Fault rules defined at ProxyEndpoint.
- Fault in target request: Fault rules defined at TargetEndpoint.
- Fault in sending request to target: Fault rules defined at TargetEndpoint.
- Response path:
- Fault in proxy response: Fault rules defined at ProxyEndpoint.
- Fault in target response: Fault rules defined at TargetEndpoint.
- Fault in sending response to proxy: Fault rules defined at ProxyEndpoint.
- Policy attachments in a fault rule are enforced in the order of their attachment.
Default fault handler
In some cases, a fault handler does not match the fault raised. A default fault handler uses the following fault rule:
- The fault is usually a first class unnamed object.
- The fault has no conditions; it always evaluates to true.
- By default, the fault is evaluated only when it does not match any fault handler.
Note: As a best practice, set the flag enforceAlways to true to allow the default handler to work on any faults captured by the specific fault handlers. In this case, you can customize the error response (by adding header, and so on) on the ProxyEndpoint.
