The main role of an Enterprise Service Bus (ESB) is to act as the backbone of an organization’s service-oriented architecture. It is the spine through which all the systems and applications within the enterprise (and external applications that integrate with the enterprise) communicate with each other. As such, an ESB often has to deal with many wire level protocols, messaging standards, and remote APIs. But applications and networks can be full of errors. Applications crash. Network routers and links get into states where they cannot pass messages through with the expected efficiency. These error conditions are very likely to cause a fault or trigger a runtime exception in the ESB.
Using fault sequences
WSO2 ESB provides fault sequences for dealing with errors. A fault sequence is a collection of mediators just like any other sequence, and it can be associated with another sequence or a proxy service. When the sequence or the proxy service encounters an error during mediation or while forwarding a message, the message that triggered the error is delegated to the specified fault sequence. Using the available mediators it is possible to log the erroneous message, forward it to a special error-tracking service, and send a SOAP fault back to the client indicating the error or even send an email to the system admin.
It is not mandatory to associate each sequence and proxy service with a fault sequence. In situations where a fault sequence is not specified explicitly, a default fault sequence will be used to handle errors. shows how to specify a fault sequence with a regular mediation sequence.
Whenever an error occurs in WSO2 ESB, the mediation engine attempts to provide as much information as possible on the error to the user by initializing the following properties on the erroneous message:
Within the fault sequence, you can access these property values using the
get-property XPath function. Sample 4 uses the log mediator as follows to log the actual error message:
<property name="text" value="An unexpected error occured"/>
<property name="message" expression="get-property('ERROR_MESSAGE')"/>
Note how the ERROR_MESSAGE property is being used to get the error message text. If you want to customize the error message that is sent back to the client, you can use the makefault mediator as demonstrated in Sample 5: Creating SOAP Fault Messages and Changing the Direction of a Message.
This section describes error codes and their meanings.
Transport error codes
|101000||Receiver input/output error sending|
|101001||Receiver input/output error receiving|
|101500||Sender input/output error sending|
|101501||Sender input/output error receiving|
|101504||Connection timed out (no input was detected on this connection over the maximum period of inactivity) |
|101506||NHTTP protocol violation|
|101508||Request to establish a new connection timed out|
|101510||Response processing failed|
If the HTTP PassThrough transport is used, and a connection level error occurs, the error code is calculated using the following equation:
There is a state machine in the transport sender side, where the protocol state changes according to the phase of the message.
Following are the possible protocol states and the description for each:
|REQUEST_READY (0)||Connection is at the initial stage ready to send a request|
|REQUEST_HEAD(1)||Sending the request headers through the connection|
|REQUEST_BODY(2)||Sending the request body|
|REQUEST_DONE(3)||Request is completely sent|
|RESPONSE_HEAD(4)||The connection is reading the response headers|
|RESPONSE_BODY(5)||The connection is reading the response body|
|RESPONSE_DONE(6)||The response is completed|
|CLOSING(7)||The connection is closing|
|CLOSED(8)||The connection is closed|
Since there are several possible protocol states in which a request can time out, you can calculate the error code accordingly using the values in the table above.
For example, in a scenario where you send a request and the request is completely sent to the backend, but a timeout happens before the response headers are received, the error code is calculated as follows:
In this scenario, the base error code is
CONNECTION_TIMEOUT(101504) and the protocol state is
Error code = 101504 + 3 = 101507
This section describes the error codes for endpoint failures. For more information on handling endpoint errors, see Endpoint Error Handling.
|303000||Load Balance endpoint is not ready to connect|
|303000||Recipient List Endpoint is not ready|
|303000||Failover endpoint is not ready to connect|
|303001||Address Endpoint is not ready to connect|
|303002||WSDL Address is not ready to connect|
Failure on endpoint in the session
|309001||Session aware load balance endpoint, No ready child endpoints|
|309002||Session aware load balance endpoint, Invalid reference|
|309003||Session aware load balance endpoint, Failed session|
|303100||A failover occurred in a Load balance endpoint|
|304100||A failover occurred in a Failover endpoint|
Referring real endpoint is null
|305100||Indirect endpoint not ready|
Callout operation failed
|401000||Callout operation failed (from the callout mediator)|
Custom error codes
Endpoint Custom Error - This error is triggered when the endpoint is prefixed by
For information on best practices for handling errors in WSO2 ESB, see WSO2 ESB by Example - Best practices for error handling on the WSO2 ESB.