All Products
Document Center

API Gateway:Troubleshooting

Last Updated:Nov 23, 2021

This topic describes how to identify and resolve issues that you may encounter when you debug APIs online.

1. Obtain error information

API Gateway returns a response to the request received from the client. You must check the response headers that start with X-Ca. Take note of the following points:

  • - X-Ca-Request-Id: the unique ID of the request. When API Gateway receives a request, it generates a request ID and contains the request ID in the X-Ca-Request-Id header of the response message. We recommend that you record the request ID in both the client and your backend service for troubleshooting and tracking.

  • - X-Ca-Error-Message: the error message returned by API Gateway. If a request fails, API Gateway contains the error message in the X-Ca-Error-Message header of the response message.

  • - X-Ca-Error-Code: the error code of a system error in API Gateway. If a request is blocked by API Gateway due to an error, API Gateway contains the corresponding error code in the X-Ca-Error-Code header of the response message. Instances of the classic network type do not have this header.


2. Use X-Ca-Request-Id to query more API call information

The X-Ca-Error-Code and X-Ca-Error-Message headers help you identify the error cause. The X-Ca-Request-Id header helps you query request logs in Log Service or query API call results in the API Gateway console. You can also provide the request ID for the technical support personnel to help them check log information and resolve issues.

To query API call results in the API Gateway console, go to the Debug page. Specify Region and X-Ca-Request-Id, and click Search. The specific log information appears.


You can also use Log Service to view API call logs. For more information about the fields in the logs, see Use Log Service to manage logs of API calls.

3. Analyze error causes

  • - If the client receives a response in which the X-Ca-Error-Code header is empty, the HTTP status code of the response is generated by your backend service. API Gateway transparently transmits the error information from your backend service. In this case, check the backend service and network configurations between API Gateway and the backend service.

  • - If the X-Ca-Error-Code header is not empty, the error code contained in the response is generated by API Gateway. The error code contains six characters in length.

  • For more information about the error code, see error code tables.