API调试及自助排错

1. 概述

API控制台支持对已发布API进行调试，而在调试过程中遇到问题时，如何理解报错信息并快速定位和解决问题。本文将结合API调试页面提供的自助排错能力进行介绍。

2. 获取错误信息

所有的API请求只要到达网关，网关就会返回请求结果信息。用户可以查看返回结果的头部，即Header部分，来获取API网关返回的信息。其中X-Ca开头的属性均为API网关返回，其中您需要重点关注的信息为：

• X-Ca-Error-Code。API网关系统错误码，当请求出现错误被网关拦截后，由API网关提供的错误码。

• X-Ca-Request-Id。请求唯一ID，请求一旦进入API网关应用后，API网关就会生成请求ID并通过响应头返回给客户端，建议客户端与后端服务都记录此请求ID，可用于问题排查与跟踪。

• X-Ca-Error-Message。API网关返回的错误消息，当请求出现错误时API网关会通过响应头将错误消息返回给客户端。

3. 根据X-Ca-Request-Id查询更多调用信息

在应答的Header中获得X-Ca-Error-Code与X-Ca-Error-Message可以基本明确报错原因，而X-Ca-Request-Id可以用于在日志服务中查询请求日志、通过控制台查询结果、或提供给支持人员进行日志排查。

控制台查询步骤如下：

1. 登录API网关控制台。

2. 在左侧栏单击调用API——自助排错，输入API所在Region以及X-Ca-Request-Id，单击查询，就可以看到对应的日志信息。

3.1. API网关报错

当您本次API网关调用响应信息中API网关错误码（X-Ca-Error-Code）不为空，说明本次调用被API网关拦截。错误码由一个6位长度的字符描述。当请求被API网关拦截时，API网关会返回相应的错误信息，并附有简单的错误原因说明（X-Ca-Error-Message），您可以根据该部分内容排查错误原因。更多错误码解释请参考错误代码表。

3.2. 后端服务报错

当您本次调用的HTTP状态码不为200，且API网关错误码为空，则表示本次调用API网关成功将请求转发到您的后端服务，后端服务经过处理后返回非200的状态码。这时候您需要检查您的后端服务业务逻辑。如果您是通过云市场购买的API，则需要咨询云市场的服务提供商。

3.3. 请求成功

当您的本次调用返回的HTTP状态码为200，则表示本次请求API网关成功转发您的请求到后端服务，并且后端服务返回成功的应答。

4. 错误原因分析

自助排错中的具体调用信息展示了您本次调用的部分日志数据，当您的调用出现失败的情况时，可以根据该部分的信息定位和排查问题。这里介绍部分字段用于快速定位出错位置：

• TotalLatency：API网关从接收到客户端请求，到完成客户端响应的总时间

• ServiceLatency：API网关向后端服务发送请求，到接收完后端服务响应的时间

通过上述两个字段可以快速分析出报错位置，当ServiceLatency为0则表示请求在API网关被拦截，未到达后端服务；当ServiceLatency不为0则表示请求到达后端服务。另外，整个请求链路的IO时间点也记录在日志中：

• FrontRequestStart：API网关开始接收到客户端请求的时间点

• FrontRequestEnd：API网关完成接收客户端请求的时间点

• BackendRequestStart：API网关开始向后端服务发起请求的时间点

• BackendRequestEnd：API网关完成向后端服务发起请求的时间点

• BackendResponseStart：API网关开始接收到后端服务响应的时间点

• BackendResponseEnd：API网关完成接收后端服务响应的时间点

• FrontResponseStart：API网关开始向客户端发送响应的时间点

• FrontResponseEnd：API网关完成向客户端发送响应的时间点

利用好请求日志信息能快速帮您解决调用问题，详细的日志字段含义请参考通过日志服务查看API调用日志。