All Products
Search
Document Center

Plug-ins of the Error Mapping type

Last Updated: Sep 28, 2020

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

    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

    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 Parameters and conditional expressions.

Location

Source

Description

StatusCode

Responses

The HTTP status code in a backend error response, such as

200

or

400

.

ErrorCode

Responses

The error code of a system error response in API Gateway.

ErrorMessage

Responses

The error message of a system error response in API Gateway.

Header

Responses

Use

Header:{Name}

to obtain the value of the HTTP header field that is specified by

{Name}

. If multiple HTTP header fields have the same name, the value of the first header field with the name is obtained.

BodyJsonField

Responses

Use

BodyJsonField:{JPath}

to obtain the JSON string in the body of an API request or a backend response.

{JPath}

is a JSONPath expression.

System

Responses

Use

System:{Name}

to obtain the value of the system parameter that is specified by

{Name}

.

Token

Responses

If JSON Web Token (JWT) is used with OAuth2 for authentication, you can use

Token:{Name}

to obtain the value of the parameter that is specified by

{Name}

, in a token.

  • 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

    OK

    .

  • 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.