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_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 <APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences/_auth_failure_handler.xml file and change application/xml to something like application/json.

API handlers error codes

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 exceeded

Hard throttle limit 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

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

Using an older access token after an access token has been renewed.

900902

Missing credentials

No authentication information provided

Accessing an API without the 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 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

The error codes 900903 (Access token expired) and 900904 (Access token inactive) are deprecated from API Manager 1.9.0 onwards. Alternatively, error code 900901 will be sent when the token is invalid or inactive.

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.

The HTTP Status Codes and the corresponding error codes from the error responses are given below.

HTTP Status Code

Error Code

401

900901, 900902, 900905, 900907, 900909

403

900906, 900908, 900910

429

900800, 900802, 900803

500

900900

503

700700, 900801

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:

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