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, for resource mismatch
errors, the _resource_mismatch_handler_.xml
file etc.
Given below are some error codes and their meanings.
API handlers error codes¶
Error code | Error Message | Description | Example |
---|---|---|---|
700700 |
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 |
900422 |
Invalid GraphQL query | Syntax of the provided GraphQL query is invalid | Invoking a GraphQL api which has a invalid query |
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 exceeded | Hard throttle limit has been reached | Invoke an API exceeding the hard throttle limit |
900802 |
Resource level throttle out | Message is throttled out because resource level has exceeded | Sending/Receiving messages beyond authorized resource level |
900803 |
Application level throttle out | Message is throttled out because application level is exceeded | Sending/Receiving messages beyond authorized application level |
900804 |
Subscription level throttled out | Message throttled out due to subscription level throttling limit reached. | Sending/Receiving messages beyond configured throttling limit of subscription level policy. |
900805 |
Message blocked | Accessing an API which is blocked on user, IP, application, or API Context. | An admin user can block API invocations in real time by user, IP, application, or API context. The API invocation meets the blocked condition. |
900806 |
Custom policy throttled out | Message throttled out due to exceeding the limit configured through the custom throttling policy rules. | The API invocations meet custom throttle policy rules, exceeding the limits of the configured custom policy. |
900807 |
Message throttled out | Messaged throttled out because of exceeding the burst control/rate limit (requests per second) in the subscription level policy. | Sending/Receiving messages exceeding the configured burst control/rate limit within second. |
900900 |
Unclassified authentication failure |
An unspecified error has occurred | Backend service for key validation is not accessible when trying to invoke an API |
900901 |
Invalid credentials |
Invalid authentication information provided. Note The error code |
When the access token is invalid, inactive or expired. |
900902 |
Missing credentials |
No authentication information provided | Accessing an API without Authorization: Bearer header |
900905 |
Incorrect 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, where the resource 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 that is not available |
900907 |
The requested API is temporarily blocked |
Happens when the API user is blocked. | Invoke API resource with a subscription that has been blocked by 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 |
The status of the API has changed to an inaccessible/unavailable state. | Invoke an API resource with a subscription 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 API resource with an access token that is not generated to be used with the resource's scope. |
102511 |
Incomplete payload | The payload sent with the request is too large and the client is unable to keep the connection alive until the payload is completely transferred to the API Gateway | Sending a large PDF file with the POST request |
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
Enterprise Integrator (WSO2 EI) documentation.
Info
The HTTP Status Codes and the corresponding error codes from the error responses are given below.
HTTP Status Code | Error Code |
---|---|
400 | 102511 |
401 | 900901, 900902, 900905, 900907, 900909, 900911 |
403 | 900906, 900908, 900910 |
422 | 900422 |
429 | 900800, 900802, 900803, 900804, 900805, 900806, 900807 |
500 | 900900 |
503 | 700700, 900801 |
Transport error codes¶
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 over the maximum period of inactivity) |
101505 | Connection closed |
101506 | NHTTP protocol violation |
101507 | Connection canceled |
101508 | Request to establish 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 code = Base error code + Protocol State
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:
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 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
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:
-
Start the WSO2 API Manager.
-
Go to
<API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences
directory and create the fileconvert.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>
Tip
Alternatively, you can use the Source View of the API-M Management Console as follows to edit the synapse configuration:
- Sign in to the Management Console.(https://<Server Host>:9443/carbon).
- Go to Manager and then Source View.
- Copy the content of the sequence in convert.xml, paste it as a new sequence in the source view and update it.
-
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 - DependencyTracker Sequence : convert was added to the Synapse configuration successfully INFO - SequenceDeployer Sequence named 'convert' has been deployed from file : <API-M_HOME>/repository/deployment/server/synapse-configs/default/sequences/convert.xml
-
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>
-
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 - DependencyTracker Sequence : _auth_failure_handler_ was added to the Synapse configuration successfully 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
-
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.curl -v -H "Authorization: Bearer <Access_Token>" http://localhost:8280/<API_name>/<version>/<context>
curl -k -v -X GET "https://localhost:8243/pizzashack/1.0.0/menu" -H "accept: application/json" -H "Authorization: Bearer fb119e84-9542-3194-93dc-1ddddaaa1111"
> GET /pizzashack/1.0.0/menu HTTP/1.1 > Host: localhost:8243 > User-Agent: curl/7.54.0 > accept: application/json > Authorization: Bearer fb119e84-9542-3194-93dc-1ddddaaa1111 > < HTTP/1.1 555 < Access-Control-Allow-Origin: * < Access-Control-Allow-Methods: GET < Access-Control-Allow-Headers: authorization,Access-Control-Allow-Origin,Content-Type,SOAPAction < Content-Type: application/json; charset=UTF-8 < Date: Fri, 04 Jan 2019 09:53:56 GMT < Transfer-Encoding: chunked < {"fault":{"code":900901,"type":"Status report","message":"Runtime Error","description":"Invalid Credentials"}}
WSO2 API Manager has the following default fault sequences located in
<API-M_HOME>
/repository/deployment/server/synapse-configs/default/sequences
directory.
Fault Sequence | Description |
---|---|
fault.xml |
This is the primary fault sequence that gets invoked when an error occurs during the execution of an API resources |
main.xml |
This sequence is called when the endpoint being called does not exist |
_auth_failure_handler_.xml |
This sequence is called when an API authentication error is encountered |
_production_key_error_.xml |
This sequence is called when a Production key is used to invoke an API that does not have a Production endpoint defined |
_sandbox_key_error_.xml |
This sequence is called when a Sandbox key is used to invoke an API that does not have a Sandbox endpoint defined |
_throttle_out_handler_.xml |
This sequence is called when a given request to an API gets throttled out |
_token_fault_.xml |
This sequence is called when there is an error in invoking the token API |
_resource_mismatch_handler_.xml |
This sequence is called when a matching resource cannot be found by the gateway to the corresponding resource being invoked |
_cors_request_handler_.xml |
This sequence enables sending CORS specific headers when the CORS specific configuration ( CORSConfiguration ) is enabled in WSO2 API Manager in the <API-M_HOME>/repository/conf/deployment.toml file. |
_threat_fault_.xml |
This sequence is called to send error messages with regard to threat detection. |
dispatchSeq.xml |
This sequence is defined as a default handler for any inbound WebSocket calls. |
outDispatchSeq.xml |
This sequence is defined to handle any outbound WebSocket calls. |
Info
The default sequences can also be customized as shown in the section above.
Custom error codes¶
Defined status codes¶
Error code | Description |
---|---|
1000 | 1000 indicates a normal closure, meaning that the purpose for which the connection was established has been fulfilled. |
1001 | 1001 indicates that an endpoint is "going away", such as a server going down or a browser having navigated away from a page. |
1002 | 1002 indicates that an endpoint is terminating the connection due to a protocol error. |
1003 | 1003 indicates that an endpoint is terminating the connection because it has received a type of data it cannot accept (e.g., an endpoint that understands only text data MAY send this if it receives a binary message). |
1004 | Reserved. The specific meaning might be defined in the future. |
1005 | 1005 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that no status code was actually present. |
1006 | 1006 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that the connection was closed abnormally, e.g., without sending or receiving a Close control frame. |
1007 | 1007 indicates that an endpoint is terminating the connection because it has received data within a message that was not consistent with the type of the message (e.g., non-UTF-8 [RFC3629] data within a text message). |
1008 | 1008 indicates that an endpoint is terminating the connection because it has received a message that violates its policy. This is a generic status code that can be returned when there is no other more suitable status code (e.g., 1003 or 1009) or if there is a need to hide specific details about the policy. |
1009 | 1009 indicates that an endpoint is terminating the connection because it has received a message that is too big for it to process. |
1010 | 1010 indicates that an endpoint (client) is terminating the connection because it has expected the server to negotiate one or more extension, but the server didn't return them in the response message of the WebSocket handshake. The list of extensions that are needed SHOULD appear in the /reason/ part of the Close frame. Note that this status code is not used by the server, because it can fail the WebSocket handshake instead. |
1011 | 1011 indicates that a server is terminating the connection because it encountered an unexpected condition that prevented it from fulfilling the request. |
1012 | 1012 indicates that the service is restarted. a client may reconnect, and if it choses to do, should reconnect using a randomized delay of 5 - 30 seconds. |
1013 | 1013 indicates that the service is experiencing overload. a client should only connect to a different IP (when there are multiple for the target) or reconnect to the same IP upon user action. |
1014 | The server was acting as a gateway or proxy and received an invalid response from the upstream server. This is similar to 502 HTTP Status Code. |
1015 | 1015 is a reserved value and MUST NOT be set as a status code in a Close control frame by an endpoint. It is designated for use in applications expecting a status code to indicate that the connection was closed due to a failure to perform a TLS handshake (e.g., the server certificate can't be verified). |
Reserved Status Code Ranges¶
Code Range | Description |
---|---|
0-999 | Status codes in the range 0-999 are not used. |
1000-2999 | Status codes in the range 1000-2999 are reserved for definition by this protocol, its future revisions, and extensions specified in a permanent and readily available public specification. |
3000-3999 | Status codes in the range 3000-3999 are reserved for use by libraries, frameworks, and applications. These status codes are registered directly with IANA. The interpretation of these codes is undefined by this protocol. |
4000-4999 | Status codes in the range 4000-4999 are reserved for private use and thus can't be registered. Such codes can be used by prior agreements between WebSocket applications. The interpretation of these codes is undefined by this protocol. |
Code | Description |
---|---|
4001 | Invalid Credentials. |
4002 | User NOT authorized to access the resource. |
4003 | Websocket frame throttled out. |
4004 | Internal server error. |
4005 | Bad request. |
4006 | Blocked from accessing the API. |
4020 | Query too deep.(Only for GraphQL subscriptions.) |
4021 | Query too complex. (Only for GraphQL subscriptions.) |
4022 | Invalid query. (Only for GraphQL subscriptions.) |