API Gateway:Plug-ins of the Error Mapping type

1. Overview

A plug-in of the Error Mapping type is used to map backend error responses to new error responses based on mapping rules that are defined as required by clients.

2. Quick start

The following example shows an error response that is returned by the backend of an API operation. The HTTP status code is 200, but the response body contains an error message in a JSON string.

HTTP 200 OK
Content-Type:application/json

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

• Assume that clients want to receive an HTTP status code other than 200 but do not want to realize this by modifying backend configurations. For example, clients expect the following error response:

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

In this case, you can configure a plug-in of the Error Mapping type by using the following sample and bind the plug-in to the relevant API operation:

---
# The parameters that are involved in mapping.
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# The mapping condition under which an error response needs to be mapped.
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# The parameter in an error response that is used to specify the error code and hit mapping rules.
errorCode: "resultCode"
# The mapping rules.
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# Optional. The default mapping rule.
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

In this example, the HTTP status code and the result_code parameter in an error response are used to define the mapping condition. If the HTTP status code of an error response is 200 and the value of the result_code parameter is not OK, the mapping starts. The result_code parameter is used to define the mapping rules. One rule is that if the value of the result_code parameter is ROLE_NOT_EXISTS, the original HTTP status code is mapped to 404. Another rule is that if the value of the result_code parameter is INVALID_PARAMETER, the original HTTP status code is mapped to 400. A default mapping rule is also defined. If the value of the result_code parameter is neither of the preceding values, the original HTTP status code is mapped to 500.

3. Plug-in configurations and mapping rules

3.1. Plug-in configurations

You can configure a plug-in of the Error Mapping type in the JSON or YAML format. The following parameters can be specified:

• parameters : required. The parameters that are involved in mapping. These parameters are specified as key-value pairs in the map format. For information about how to define parameters and write conditional expressions, see Use parameters and conditional expressions.

• errorCondition: required. The mapping condition under which an error response needs to be mapped. If the result of the conditional expression is true, the mapping starts.

• errorCode: optional. The parameter in an error response that is used to specify the error code and hit mapping rules. The error code that is specified by the value of the errorCode parameter is compared with the value of the code parameter in the mapping rules.

• mappings: required. The mapping rules. API Gateway reconstructs error responses based on these mapping rules. A mapping rule may contain the following parameters:

  • code: optional. A specified value that is used to identify an error response whose error code that is specified by the value of the errorCode parameter is the same. The value of this parameter must be unique among all mapping rules. If the error code of an error response is the same as the value of the code parameter in the current mapping rule, the error response is mapped based on the current rule.

  • condition: optional. The condition under which an error response needs to be mapped based on the current mapping rule. If the result of the conditional expression is true, the error response is mapped based on the current rule.

  • statusCode: required. The HTTP status code that replaces the original HTTP status code of an error response if the error response needs to be mapped based on the current mapping rule.

  • errorMessage: optional. The error message that is returned to the client after mapping. The value of this parameter is obtained from the parameters in the original backend error response and is also stored in the errorMessage parameter in error logs. In the error response after mapping, this parameter is displayed as the value of the X-Ca-Error-Message header field.

  • responseHeaders: optional. The response header fields that are included in the error response after mapping if the current mapping rule is hit. This parameter is specified as key-value pairs in the map format.

  • responseBody: optional. The response body that overwrites the original response body of an error response if the error response needs to be mapped based on the current mapping rule.

• defaultMapping: optional. The default mapping rule. If an error response does not hit rules that are defined in the mappings parameter, the error response is mapped based on the default mapping rule.

  • statusCode: required. The HTTP status code that replaces the original HTTP status code of an error response if the error response needs to be mapped based on the default mapping rule.

  • errorMessage: optional. The error message that is returned to the client after mapping. The value of this parameter is obtained from the parameters in the original backend error response and is also stored in the errorMessage parameter in error logs. In the error response after mapping, this parameter is displayed as the value of the X-Ca-Error-Message header field.

  • responseHeaders: optional. The response header fields that are included in the error response after mapping if the default mapping rule is hit. This parameter is specified as key-value pairs in the map format.

  • responseBody: optional. The response body that overwrites the original response body of an error response if the error response needs to be mapped based on the default mapping rule.

Take note of the following items when you configure a plug-in of the Error Mapping type:

• The parameters that are used to write conditional expressions in mappingCondition and mappings[].condition must be defined in the parameters parameter. Otherwise, the plug-in does not work and reports an error. For information about how to define parameters and write conditional expressions, see Use parameters and conditional expressions.

• The value of the errorCode parameter must be the name of a parameter that is defined in the parameters parameter.

• When you configure a mapping rule, you must specify at least one of the code and condition parameters. When you specify the code parameter, the value of this parameter must be unique among all mapping rules. When you specify the condition parameter, you must write conditional expressions in the order that meets your requirements. This is because the order of conditions determines their priorities.

• You can replace the errorMessage and responseBody parameters with the "${Code}: ${Message}" format. The values of the Code and Message parameters in this format must be obtained from the parameters that are defined in the parameters parameter.

• You can also replace the responseHeaders parameter with the ${Message} format.

• If you do not specify the responseBody parameter, the response body of the error response that is returned to the client after mapping is the same as that of the original error response.

• You can use the responseHeaders parameter to specify header fields and their values to replace corresponding header fields in a backend error response. If you specify the value of a header field as '', this header field will be deleted after mapping. If you do not specify this parameter, the header fields of the error response that is returned to the client after mapping are the same as those of the original error response.

• If you do not specify the defaultMapping parameter and an error response does not hit mapping rules, the original backend error response is returned to the client.

3.2. Parameters involved in mapping

As shown in the following code snippet, you must specify parameters that are involved in mapping as key-value pairs in the parameters parameter. Each key is the name of a parameter. Each value is specified in the Location:Name format. This format indicates that the value of the parameter is obtained from a response or the context of the system.

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

You can specify the following locations when you use the `Location:Name` format to obtain parameter values. For more information about the locations, see Use parameters and conditional expressions.

• The ErrorCode and ErrorMessage locations are used to obtain error codes and error messages in system error responses in API Gateway. For more information, see Error code table.

• The BodyJsonField location can be used to obtain the JSON string in the body of a backend response. However, if the size of the response body exceeds 16,380 bytes, the obtained string is

  null.

3.3. Working mechanism

The following actions describe how a plug-in of the Error Mapping type works:

• 1. Step 1: Based on the list of parameters that are defined in the parameters parameter, obtain the values of the parameters from a backend error response and the context of the system.

• 1. Step 2: Use the parameters and obtained values to execute the conditional expression that is written in the errorCondition parameter. If the result is true, go to the next step. If the result is false, the process ends.

• 1. Step 3: If the errorCode parameter is specified, obtain the error code that is specified by the value of the errorCode parameter. Then, check if the error code is equal to the value of the code parameter in mapping rules.

• 1. Step 4: If no mapping rule is hit in step 3, execute in sequence the conditional expressions that are written in the condition parameter in mapping rules.

• 1. Step 5: If a mapping rule is hit in step 3 or step 4, the original error response is mapped based on the mapping rule. Otherwise, the original error response is mapped based on the default mapping rule.

3.4. Mapping of system error responses and error logs

• In API Gateway, system errors may occur in processes such as checking, verification, throttling, and plug-in operation. For more information, see Error code table. You can use ErrorCode as a location to obtain information in a system error response. For example, clients support only HTTP status code 200 and want to map HTTP status code 429 that is returned by API Gateway to HTTP status code 200.

• For a system error response, the values that are obtained from locations such as StatusCode, Header, and BodyJsonField are all null. When you define the mapping condition for a plug-in of the Error Mapping type, note that for a backend error response, the value that is obtained from the ErrorCode location is O.

• The error code of a system error response is returned as the value of the X-Ca-Error-Code header field and is also stored in the errorCode parameter in error logs. This value cannot be overwritten by using a plug-in of the Error Mapping type.

• The statusCode parameter in error logs records the value of the HTTP status code that is sent from API Gateway to the client. This value can be overwritten by using a plug-in of the Error Mapping type.

4. Configuration examples

4.1. Use error codes in error responses for error mapping

Mapping

---
# The parameters that are involved in mapping.
parameters:
  statusCode: "StatusCode"
  resultCode: "BodyJsonField:$.result_code"
  resultId: "BodyJsonField:$.req_msg_id"
# The mapping condition under which an error response needs to be mapped.
errorCondition: "$statusCode = 200 and $resultCode <> 'OK'"
# The parameter in an error response that is used to specify the error code and hit mapping rules.
errorCode: "resultCode"
# The mapping rules.
mappings:
  - code: "ROLE_NOT_EXISTS"
    statusCode: 404
    errorMessage: "Role Not Exists, RequestId=${resultId}"
  - code: "INVALID_PARAMETER"
    statusCode: 400
    errorMessage: "Invalid Parameter, RequestId=${resultId}"
# Optional. The default mapping rule.
defaultMapping:
  statusCode: 500
  errorMessage: "Unknown Error, ${resultCode}, RequestId=${resultId}"

5. Limits

• A maximum of 16 parameters can be defined in each plug-in of the Error Mapping type.

• Each conditional expression can contain a maximum of 512 characters.

• If you use the BodyJsonField location to obtain the JSON string in the body of an error response, the response body can be a maximum of 16,380 bytes in size. If the size of the response body exceeds this limit, the obtained string is null.

• For each plug-in of the Error Mapping type, you can configure a maximum of 16,380 bytes of metadata.

• For each plug-in of the Error Mapping type, you can configure a maximum of 20 mapping rules by using the condition parameter.