Date: Mon, 9 Dec 2019 23:51:55 -0800 (PST) Message-ID: <> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_6827_1298295127.1575964315274" ------=_Part_6827_1298295127.1575964315274 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html Error Handling

Error Handling

The main role of an Enterprise Service Bus (ESB) is= to act as the backbone of an organization=E2=80=99s service-oriented archi= tecture. It is the spine through which all the systems and applications wit= hin the enterprise (and external applications that integrate with the enter= prise) communicate with each other. As such, an ESB often has to deal with = many wire level protocols, messaging standards, and remote APIs. But applic= ations and networks can be full of errors. Applications crash. Network rout= ers 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 provid= es fault sequences for dealing with errors. A fault sequence is a collectio= n 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 me= ssage 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 bac= k to the client indicating the error or even send an email to the system ad= min.

It is not mandatory to associate each sequence and proxy se= rvice with a fault sequence. In situations where a fault sequence is not sp= ecified explicitly, a default fault sequence will be used to handle errors.= Sample 4: Introduction to Error Handl= ing s= hows 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 use= r by initializing the following properties on the erroneous message:=

Within the faul= t sequence, you can access these property values using the get-proper= ty XPath function. Sample 4 uses the log mediator as follows to log = the actual error message:  
<log level=3D"custom">
  <pro= perty name=3D"text" value=3D"An unexpected error occured"/>
 &nbs= p;  <property name=3D"message" expression=3D"get-property('ER= ROR_MESSAGE')"/>      
</log> Note how the ERROR_MESSAGE property is being used to get th= e error message text. If you want to customize the error message that is se= nt back to the client, you can use the makefault mediator as demonstrated in Sample 5: Creating SOAP Fault Messages and Changing the Direction o= f a Message.

Error codes

This section describes error codes and their meanings.

Transport error codes

=20 =20 =20
Error Code Detail
101000 Receiver input/output error sending
101001 Receiver input/output error receiving
101500 Sender input/output error sending
101501 Sender input/output error receiving
101503 Connection failed
101504 Connection timed out (no input was detected on this connection ove= r the maximum period of inactivity)
101505 Connection closed
101506 NHTTP protocol violation

Connection canceled

101508 Request to establish a new connection timed out
101509 Send abort
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:

Error c=
ode =3D Base error code + Protocol State

There is a state machine in the transport sender side, where the protoco= l state changes according to the phase of the message.

Following are the possible protocol states and the description for each:=

Protocol State Description
REQUEST_READY (0) Connection is at the initial stage ready to send= a request
REQUEST_HEAD(1) Sending the request headers through the connecti= on
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 c= ompletely sent to the backend, but a timeout happens before the respon= se 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 REQUEST_DONE(3).


Error code =3D 101504 + 3 =3D 101507

Endpoint failures

This section describes the error codes for endpoint failures. For more i= nformation on handling endpoint errors, see Endpoint Error Handling.

General errors

=20 =20 =20
Error Code Detail
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

=20 =20 =20
Error Code Detail
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

Non-fatal warnings

=20 =20 =20
Error Code Detail
303100 A failover occurred in a Load balance endpoint
304100 A failover occurred in a Failover endpoint

Referring real endpoint is null

=20 =20 =20
Error Code Detail
305100 Indirect endpoint not ready

Callout operation failed

=20 =20 =20
Error Code Detail
401000 Callout operation failed (from the callout mediator)
401001 Blocking call operation failed (fr= om the Call mediator when you have enabled blocking in it).
401002 Blocking sender operation failed (= from the Call mediator when you have enabled blocking in it).

Custom error codes

=20 =20 =20
Erro= r Code Deta= il

Endpoint Custom Error - This error is trigger= ed when the endpoint is prefixed by <property name=3D"FORCE_ERROR_= ON_SOAP_FAULT" value=3D"true"/>, which enhances the failover logi= c by marking an endpoint as suspended when the response is a SOAP fault.

For information on best practices for handling errors in WSO2 ESB, see&n= bsp;WSO2 ESB by Example - Best practices for error handling on the WSO2 E= SB.