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 <AM<APIM_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 <AM<APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences/_auth_failure_handler.xml
file and change file and change application/xml
to something like application/json
.
Code Block | ||
---|---|---|
| ||
<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.
Table of Contents |
---|
...
Error code | Error Message | Description | Example |
---|---|---|---|
| API blocked | This API has been blocked temporarily. Please try again later or contact the system administrators. | Invoke an API which is in "the BLOCKED" lifecycle state |
900800 | Message throttled out | The maximum number of requests that can be made to the API within a designated time period is reached and the API is throttled for the user. | Invoke an API exceeding the tier limit |
900801 | Hard Limit Exceededlimit exceeded | Hard throttle limit has been reached. | Invoke an API exceeding the hard throttle limit |
900900 | Unclassified Authentication authentication Failure | An unspecified error has occurred. | Backend service for key validation is not accessible when trying to invoke an API |
900901 | Invalid Credentialscredentials | Invalid Authentication authentication information provided. | Using an older access token while after an access token has been renewed. |
900902 | Missing Credentialscredentials | No authentication information provided. | Accessing an API without "the Authorization: Bearer" header |
900905 | Incorrect Access Token Type access token type is provided | The access token type used is not supported when invoking the API. The supported access token types are application and user accesses tokens. See Access Tokens. | Invoke an API with application token, But where the resource is only allows application user tokens |
900906 | No matching resource found in the API for the given request | A resource with the name in the request can not be found in the API. | Invoke an API resource which that is not available |
900907 | The requested API is temporarily blocked | The status of the API has been changed to an inaccessible/unavailable state. | Invoke an API resource with a subscription which that has been blocked in the API publisher |
900908 | Resource forbidden | The user invoking the API has not been granted access to the required resource. | Invoke an unsubscribed API |
900909 | The subscription to the API is inactive | Happens when the API user is blocked. | Invoke an API resource with a subscription which that has not yet been approved by the administrator. |
900910 | The access token does not allow you to access the requested resource | Can not access the required resource with the provided access token. Check the valid resources that can be accessed with this token. | Invoke an API resource with an access token which that is not generated to be used with the resource's scope. |
Sequences error codes
Error code | Description |
---|---|
900901 | Production/sandbox key offered to the API with no production/sandbox endpoint. |
400 | Server cannot process the request due to an error in the request sent by the client. |
403 | No matching resource found in the API for the given request. |
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 ESB documentation.
...
Go to
<APIM_HOME>
/repository/deployment/server/synapse-configs/default/sequences
directory and create the fileconvert.xml
as follows.Code Block language xml <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>
Tip Alternatively, you can use the Source View of the APIm 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.
- Start the API Manager and log in to the Management Console. (
Check the logs to see whether there are issues in the deployment. If the deployment is successful, you see a message like the following in the system logs:
Background Color color default [2015-04-13 09:17:38,885] INFO - SequenceDeployer Sequence named 'convert' has been deployed from file :
<APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences/convert.xml
Invoke the API until the throttling limit exceeds and the new requests get throttled out.
Code Block curl -v -H "Authorization: Bearer <Access_Token>" http://localhost:8280/<API_name>/<context>/<version>
Note that you get following response:
Code Block language xml * About to connect() to 127.0.0.1 port 8280 (#0) * Trying 127.0.0.1... * Adding handle: conn: 0x17a2db0 * Adding handle: send: 0 * Adding handle: recv: 0 * Curl_addHandleToPipeline: length: 1 * - Conn 0 (0x17a2db0) send_pipe: 1, recv_pipe: 0 * Connected to 127.0.0.1 (127.0.0.1) port 8280 (#0) > GET /testam/sanjeewa/1.0.0 HTTP/1.1 > User-Agent: curl/7.32.0 > Host: 127.0.0.1:8280 > Accept: */* > Authorization: Bearer 7f855a7d70aed820a78367c362385c86 > < HTTP/1.1 555 < Access-Control-Allow-Origin: * < Content-Type: application/json < Date: Mon, 13 Apr 2015 05:30:12 GMT * Server WSO2-PassThrough-HTTP is not blacklisted < Server: WSO2-PassThrough-HTTP < Transfer-Encoding: chunked < * Connection #0 to host 127.0.0.1 left intact {"fault":{"code":"900800","type":"Status report","message":"Runtime Error","description":"Message throttled out"}}