Troubleshoot issues that occur during API debugging

Read error information from response headers

API Gateway returns a response for every request it receives. Headers prefixed with X-Ca carry diagnostic information returned by API Gateway. The three most useful headers for troubleshooting are:

• X-Ca-Error-Code: the error code. Present only when API Gateway rejects the request.

• X-Ca-Request-Id: the unique request ID. API Gateway generates and returns this ID for every request. Record it in both your client and backend service — it is your primary handle for tracing and troubleshooting.

• X-Ca-Error-Message: the error message. Returned alongside X-Ca-Error-Code when a request fails.

Look up call details by X-Ca-Request-Id

Use X-Ca-Error-Code and X-Ca-Error-Message to identify the initial failure. Three outcomes are possible:

Errors reported by API Gateway

If X-Ca-Error-Code is not empty, API Gateway rejected the request. The error code is a six-character string. Use X-Ca-Error-Message for a brief description of the cause. For the full list of error codes, see Error codes.

Errors reported by the backend service

If the HTTP status code is not 200 and X-Ca-Error-Code is empty, API Gateway forwarded the request successfully but the backend service returned a non-200 response. Check your backend service logic. If you purchased the API from Alibaba Cloud Marketplace, contact the service provider.

Successful request

If the HTTP status code is 200, API Gateway forwarded the request and the backend service returned a successful response.

For deeper investigation, use X-Ca-Request-Id to query detailed request logs in Simple Log Service and view results in the API Gateway console. You can also share it with technical support.

To look up a request in the console:

1. Log on to the API Gateway console.

2. In the left navigation pane, click Call APIs > Troubleshooting. Enter the Region of the API Gateway and the X-Ca-Request-Id, then click Query.

Get trace logs

After sending a request on the API debugging page, you can view its trace log. The log captures the full request lifecycle: the request API Gateway receives from the client, processing steps inside API Gateway, the request API Gateway sends to the backend service, the backend response, and the final response returned to the client.

If you are using a RAM user account or an assumed role, select Record Trace log before sending the request. The account must also have the apigateway:AcquireGatewayToken permission granted by the root account for the instance where the API resides. For more information about granting permissions, see Use RAM to manage APIs.

The following example shows the policy statement that grants this permission:

{
 "Version": "1",
 "Statement": [
 {
 "Effect": "ALLOW",
 "Action": "apigateway:AcquireGatewayToken",
 "Resource": "acs:apigateway:{#regionId}:{#accountId}:instance/{#InstanceId}"
 }
 ]
}
# The {#} symbol indicates a variable that you must replace with an actual value.

Analyze errors using the Diagnostics tab

In the Call information section of the Diagnostics tab, you can inspect logs for any call. Two latency fields let you immediately pinpoint whether a failure originated inside API Gateway or in the backend service:

• TotalLatency: the total time from when API Gateway receives the client request to when it sends a complete response back to the client.

• ServiceLatency: the time from when API Gateway sends the request to the backend service to when it receives a complete response.

If ServiceLatency is 0, the request was intercepted by API Gateway and never reached the backend service. If ServiceLatency is greater than 0, the request reached the backend service.

The log also records I/O timestamps for each stage of the request path:

For more information about log fields, see Use Simple Log Service to manage logs of API calls.