how to use the error code mapping plug-in - API Gateway - Alibaba Cloud Documentation Center

1. Overview

Use this plug-in to transform backend error responses into the format that your clients expect.

2. Getting started

In the following example, a backend returns an HTTP 200 response, but the response body contains an error message in a JSON field.

HTTP 200 OK
Content-Type:application/json

{"req_msg_id":"d02afa56394f4588832bed46614e1772","result_code":"ROLE_NOT_EXISTS"}

In this scenario, the client expects a non-200 response, which you want to provide without modifying the backend.

HTTP 404 
X-Ca-Error-Message: Role Not Exists, ResultId=d02afa56394f4588832bed46614e1772

To handle this, configure the error code mapping plug-in as follows.

---
# Fields involved in mapping
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# Mapping condition
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# Error code field
errorCode: "resultCode"
# Mapping items
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# Default mapping (optional)
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

In this example, the mapping condition is based on the backend response code and the result_code field in the JSON response body. Error code mapping is triggered if the backend response code is 200 but the result_code field is not 'OK'. The value of the result_code field is used as the error code for the mapping. Two error codes are configured: ROLE_NOT_EXISTS returns a 404 response to the client, and INVALID_PARAMETER returns a 400 response. All other error codes return a 500 response.

3. Plug-in configuration and mapping rules

3.1. Plug-in configuration

Configure the error mapping plug-in in json or yaml format. The configuration fields are:

parameters (Required): The parameters used for the mapping. These parameters are configured as a map. For more information, see Using Parameters and Conditional Expressions.
errorCondition (Required): A conditional expression that determines whether a response is an error. If the expression evaluates to true, the mapping is executed.
errorCode (Optional): Specifies the parameter that provides the error code. The value of this parameter is used to match the code field in the mappings list.
mappings (Required): A list of mapping records. The gateway reconstructs the response based on the record that matches the error code or error condition. The fields are:
- code (Optional): A unique identifier. If you set this parameter, the errorCode parameter is required. When the value of the errorCode parameter matches the value of this code parameter, the current mapping record is executed.
- condition (Optional): An error conditional expression. When the expression evaluates to true, the current mapping record is executed.
- statusCode (Required): The HTTP status code for the current mapping record.
- errorMessage (Optional): The error message for the current mapping record. This message appears in the X-Ca-Error-Message response header and the errorMessage field in the logs.
- responseHeaders (Optional): The response headers for the current mapping record, configured as a map.
- responseBody (Optional): The response body that overwrites the original response body for the current mapping record.
defaultMapping (Optional): The default mapping record. If no records in mappings are matched, this record is used for the response.
- statusCode (Required): The HTTP status code for the current mapping record.
- errorMessage (Optional): The error message for the current mapping record. This message appears in the X-Ca-Error-Message response header and the errorMessage field in the logs.
- responseHeaders (Optional): The response headers for the current mapping record, configured as a map.
- responseBody (Optional): The response body that overwrites the original response body for the current mapping record.

Configuration rules:

The parameters used in the conditional expressions for mappingCondition and mappings[].condition must be defined in the parameters field. Otherwise, an error occurs. For more information about parameter definitions and conditional expressions, see Using Parameters and Conditional Expressions.
The parameter used in the errorCode field must be defined in parameters.
For each record in the mappings list, you must configure either a code or a condition. If you configure code, its value must be unique within the list. If you configure condition, the records are evaluated in the order they are listed. The first matching record is executed.
For errorMessage and responseBody, you can use a template format such as "${Code}: ${Message}" to replace variables. The parameter values are retrieved from the values extracted by the parameters configuration.
The values in responseHeaders can also use the ${Message} format for template replacement.
If responseBody is not configured, the backend response body is passed through.
If responseHeaders is not configured, the backend response headers are passed through. Otherwise, the configured key-value pairs overwrite the backend response headers. If a value is set to '', the corresponding header is deleted.
If defaultMapping is not configured, the backend response is passed through without error code mapping.

3.2. Mapping parameters

Mapping parameters are configured as key-value pairs in the parameters field. The key is the variable name, and the value uses the Location:Name format to retrieve a value from a specific location in the response or system context.

---
# Fields involved in mapping
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"

The following locations are available for error code mappings. For more information, see Using Parameters and Conditional Expressions.

Location name	Scope	Description
StatusCode	Response	The HTTP response code from the backend, such as `200` or `400`.
ErrorCode	Response	The API Gateway system error code.
ErrorMessage	Response	The API Gateway system error message.
Header	Response	Use `Header:{Name}` to get the first value of the HTTP header named `{Name}`.
BodyJsonField	Response*	Use `BodyJson:{JPath}` to get the value of a JSON field from the request or response body using a `JSONPath` expression.
System	Response	Use `System:{Name}` to get the value of the system parameter named `{Name}`.
Token	Response	In `jwt` or `oauth2` authorization scenarios, use `Token:{Name}` to get the value of a claim named `{Name}` from the token.

ErrorCode and ErrorMessage retrieve system error codes and messages from API Gateway. For more information, see the Error Code Table document.
Using BodyJsonField lets you use JSONPath to extract values from the backend's JSON response. However, if the backend response body exceeds 15,360 bytes, this parameter cannot be extracted and returns a null value.

3.3. Execution rules

The error code mapping plug-in executes in the following order.

The plug-in retrieves the current parameter values from the response and system context based on the parameter list configured in parameters.
The plug-in executes the conditional expression configured in errorCondition using the parameter values from step 1. If the expression evaluates to true, the process continues. If it evaluates to false, the plug-in stops and performs no mapping.
If the errorCode parameter is configured, the plug-in retrieves its value and searches for a mapping record in mappings where the code value matches.
If no matching record is found in step 3, the plug-in sequentially evaluates the condition of each mapping record in mappings until a match is found.
If a mapping record is matched in step 3 or 4, the gateway constructs a new response based on that record's configuration. Otherwise, the gateway constructs the response based on the defaultMapping configuration.

3.4. System error mapping and logs

API Gateway system errors can occur during gateway checks, validation, throttling, and plug-in processing. You can use the ErrorCode parameter to map these system error codes. For example, you can map a throttled 429 response to a 200 response for a client that only supports 200 responses. For a list of system error codes, see the Error Code Table document.
When a system error occurs, the values of parameters retrieved from the response, such as StatusCode, Header, and BodyJsonField, are null. Keep this in mind when you write conditional expressions. When no system error occurs, the value retrieved from the ErrorCode location is OK.
The API Gateway system error code appears in the X-Ca-Error-Code response header and the errorCode field in the logs. The error code mapping plug-in does not overwrite this value.
The statusCode field in the logs records the response code that the gateway delivers to the client. The error code mapping plug-in can overwrite this value.

4. Configuration examples

4.1. Map body error codes

Mapping

---
# Fields involved in mapping
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# Mapping condition
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# Error code field
errorCode: "resultCode"
# Mapping items
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# Default mapping (optional)
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

4.2. Map response body

#
# This example returns a custom JSON error body to the frontend.
---
# Specify mapping parameters
parameters:
  statusCode: "StatusCode"
  resultCode: "Header:X-Ca-Error-Code"
  requestId: "Header:X-Ca-Request-Id"
  errorMessage: "Header:X-Ca-Error-Message"

# Mapping condition
errorCondition: "$statusCode != 200"
# Error code field
errorCode: "resultCode"
# Mapping items
mappings:
  - code: "I400MH"
    statusCode: 200
    responseHeaders:
        Content-Type: "application/xml"
        X-Ca-Error-Message: ""
        X-Ca-Error-Code: ""
    responseBody: |
        {
            "code":"89",
            "message":"${errorMessage}",
            "resultCode":"${resultCode}"
            
        }

5. Limits

You can define a maximum of 16 parameters.
Each expression can contain a maximum of 512 characters.
For the BodyJsonField location, the response body is limited to 16,380 bytes. If the body exceeds this size, a null value is returned.
The plug-in configuration size is limited to 50 KB.
You can configure a maximum of 20 mapping records using the condition method in mappings.