Error Handling

When errors/exceptions occur in the system, the API Manager throws XML-based error responses to the client by default. To change the format of these error responses, you change the relevant XML file in the <API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences directory. The directory includes multiple XML files, named after the type of errors that occur. You must select the correct file.

For example, to change the message type of authorization errors, open the <API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences/_auth_failure_handler.xml  file and change  application/xml to something like  application/json .

<sequence name="_auth_failure_handler_" xmlns="http://ws.apache.org/ns/synapse">
 <property name="error_message_type" value="application/json"/>
 <sequence key="_cors_request_handler_"/>
</sequence>

Similarly, to change the error messages of throttling errors (e.g., quota exceeding), change the _throttle_out_handler_.xml file; resource mismatch errors, the _resource_mismatch_handler_.xml file, etc.

Given below are some error codes and their meanings.

API handlers error codes

700700

900800

900801

900900

900901

900902

900905

900906

900907

900908

900909

900910

Sequences error codes

900901

400

403

In addition to the above error codes, we have engaged Synapse-level error codes to the default fault sequence and custom fault sequences (e.g., _token_fault_.xml ) of the API Manager. For information, see Error Handling  in WSO2 Enterprise Integrator (WSO2 EI) documentation.

Transport error codes

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:

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 REQUEST_DONE(3).

Therefore, 

Error code = 101504 + 3 = 101507

These Transport error codes are used in Advanced Configurations of Endpoints.

Custom error messages

To send a custom message with a custom HTTP status code, you execute an additional sequence that can generate a new error message. You then override the message body, HTTP status code and other values.

The following steps demonstrate how to override a throttled-out message's HTTP status code as a custom error message:

1. Go to <API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences directory and create the file convert.xml as follows.

   <sequence xmlns="http://ws.apache.org/ns/synapse" name="convert">
       <payloadFactory media-type="xml">
           <format>
               <am:fault xmlns:am="http://wso2.org/apimanager">
                   <am:code>$1</am:code>
                   <am:type>Status report</am:type>
                   <am:message>Runtime Error</am:message>
                   <am:description>$2</am:description>
               </am:fault>
           </format>
           <args>
               <arg evaluator="xml" expression="$ctx:ERROR_CODE"/>
               <arg evaluator="xml" expression="$ctx:ERROR_MESSAGE"/>
           </args>
       </payloadFactory>
       <property name="RESPONSE" value="true"/>
       <header name="To" action="remove"/>
       <property name="HTTP_SC" value="555" scope="axis2"/>
       <property name="NO_ENTITY_BODY" scope="axis2" action="remove"/>
       <property name="ContentType" scope="axis2" action="remove"/>
       <property name="Authorization" scope="transport" action="remove"/>
       <property name="Access-Control-Allow-Origin" value="*" scope="transport"/>
       <property name="Host" scope="transport" action="remove"/>
       <property name="Accept" scope="transport" action="remove"/>
       <property name="X-JWT-Assertion" scope="transport" action="remove"/>
       <property name="messageType" value="application/json" scope="axis2"/>
       <send/>
   </sequence>

   Alternatively, you can use the Source View of the API-M Management Console as follows to edit the synapse configuration:

   • Start the API Manager and log in to the Management Console. (https://<Server Host>:9443/carbon).
   • Go to Manager -> Source View.
   • Copy the content of the sequence in convert.xml, paste it as a new sequence in the source view and update it.

2. Check the terminal logs to see whether there are issues in the deployment. 
   If the deployment is successful, you see a message similar to the following in the system logs:

   INFO - SequenceDeployer Sequence named 'convert' has been deployed from file : <API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences/convert.xml

3. Include the sequence that you just deployed in a sequence of your choice.
For this example, let's add this custom sequence in the _auth_failure_handler_ sequence.

   <sequence name="_auth_failure_handler_" xmlns="http://ws.apache.org/ns/synapse">
       ...
       <sequence key="convert"/>
       <drop/>
   </sequence>

4. Check the terminal and see whether there are any errors with the _auth_failure_handler_ sequence deployment.
   If the deployment is successful, you see a message similar to the following in the system logs:

   INFO - SequenceDeployer Sequence: _auth_failure_handler_ has been updated from the file: <API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences/_auth_failure_handler_.xml

5. Invoke the API with the respective criteria in order to trigger the sequence. 
   In this example, let's view the menu on the PizzaShack API and invoke the API with an incorrect token.

WSO2 API Manager has the following default fault sequences located in <API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences directory.