All Products
Search

This Product

    API Gateway:Troubleshoot issues that occur during API debugging

    Document Center

    API Gateway:Troubleshoot issues that occur during API debugging

    Last Updated:Apr 02, 2024

    API Gateway allows you to debug published APIs online. This topic describes how to troubleshoot issues that occur during API debugging.

    1. Overview

    The API Gateway console allows you to debug published APIs. If an issue occurs during the debugging process, you can locate and resolve the issue based on the error information. This topic describes how you can do that by using the API debug feature provided by the API Gateway console.

    Note

    • The API debug feature supports three authentication methods: signature authentication, simple authentication (AppCode), and basic authentication plug-in (BasicAuth plug-in) authentication.

    • The API debug feature supports multipart and form-data. You can upload files on the debugging page.

    • The maximum size of a request packet used on the debugging page is 512 KB. If your request packet is larger than 512 KB in size, we recommend that you use SDKs for debugging.

    • The blacklist, whitelist, or IP address-based throttling plug-in that you configure on an instance must allow the IP address that you want to use for the debugging. You can obtain the IP address from the lower-left corner of the API debugging page.

    2. Obtain error information

    API Gateway returns a response for every received request. You can view API Gateway-returned information from the headers of the response. The attributes that start with X-Ca are returned by API Gateway. We recommend that you focus on the following information:

    • X-Ca-Error-Code: the system error code. This attribute is returned if the request has an error and is rejected by API Gateway.

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

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

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

    You can obtain the basic information about a call failure from the X-Ca-Error-Code and X-Ca-Error-Message headers in a response. If you require more information, you can use the X-Ca-Request-Id header to query request logs in Simple Log Service and request results in the API Gateway console. You can also provide the X-Ca-Request-Id header to technical support engineers for further troubleshooting.

    To query call logs in the API Gateway console, perform the following steps:

    1. Log on to the API Gateway console.

    2. In the left-side navigation pane, choose Call APIs > Troubleshooting. On the page that appears, specify the region and X-Ca-Request-Id of the API and then click Query to view the corresponding log.

    Note

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

    2.1.1 Errors reported by API Gateway

    If the X-Ca-Error-Code header is not empty, the request is rejected by API Gateway.. The error code is a string of six characters. Along with the error code, an error message and a brief error cause description are also returned (X-Ca-Error-Message). You can troubleshoot the error based on the information. For more information about error codes, see Error codes.

    2.1.2 Errors reported by a backend service

    If the HTTP status code is not 200 and the X-Ca-Error-Code header is empty, API Gateway has forwarded the request to your backend service, which then processes the request and returns a non-200 status code. In this case, you must check the business logic of your backend service. If you purchased the API from Alibaba Cloud Marketplace, you must contact the service provider in Alibaba Cloud Marketplace.

    2.1.3 Success

    If the HTTP status code is 200, API Gateway has forwarded the request to the backend service, and the backend service returns a success response after it processes the request.

    3. Obtain trace logs

    If you select Record Trace, you can view the request received by API Gateway, processing information, request forwarded by API Gateway to the backend service, response received by API Gateway, and response forwarded by API Gateway to the client in trace logs.

    If you are using a Resource Access Management (RAM) user or a RAM role, you must make sure that you are granted permissions on the AcquireGatewayToken operation of the instance on which the API resides by an Alibaba Cloud account. The following sample code provides an example. For more information, see Use RAM to manage the permissions on API resources. 

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

    4. Analyze the cause

    In the Call information section of the Diagnostics tab, you can view some logs of this call. You can troubleshoot the issue based on the logs if your call fails. The following two fields can be used to quickly locate an issue:

    • TotalLatency: the duration from when API Gateway receives the request to when the client receives a response.

    • ServiceLatency: the duration from when API Gateway forwards the request to when API Gateway receives a response from the backend service.

    If the value of ServiceLatency is 0, the request is rejected by API Gateway. If the value of ServiceLatency is not 0, the request is forwarded to the backend service. In addition, the input/output (I/O) points in time of the entire request link are recorded in logs:

    • FrontRequestStart: the point in time when API Gateway starts to receive the client request

    • FrontRequestEnd: the point in time when API Gateway completes receiving the client request

    • BackendRequestStart: the point in time when API Gateway starts to forward the request to the backend service

    • BackendRequestEnd: the point in time when API Gateway completes forwarding the request to the backend service

    • BackendResponseStart: the point in time when API Gateway starts to receive a response from the backend service

    • BackendResponseEnd: the point in time when API Gateway completes receiving the response from the backend service

    • FrontResponseStart: the point in time when API Gateway starts to send a response to the client

    • FrontResponseEnd: the point in time when API Gateway completes sending the response to the client

    Properly used logs can help you quickly resolve issues. For more information about fields in logs, see Use Simple Log Service to manage logs of API calls.