当您在API调试或线上系统遇到问题时,本文可以帮助您快速定位API问题位置,方便您及时排错。
1、获取错误信息
所有的 API 请求只要到达了网关,网关就会返回请求结果信息。用户需要查看返回结果的头部,即 Header 部分。其中 X-Ca开头的均为网关返回,您需要重点关注的信息:
- X-Ca-Request-Id。请求唯一ID,请求一旦进入API网关应用后,API网关就会生成请求ID并通过响应头返回给客户端,建议客户端与后端服务都记录此请求ID,可用于问题排查与跟踪
- X-Ca-Error-Message。API网关返回的错误消息,当请求出现错误时API网关会通过响应头将错误消息返回给客户端
- X-Ca-Error-Code。API网关系统错误码,当请求出现错误被网关拦截后,由API网关提供的错误码。

2、根据X-Ca-Request-Id查询更多调用信息
在应答的Header
中获得X-Ca-Error-Code
与X-Ca-Error-Message
可以基本明确报错原因,而X-Ca-Request-Id
可以用于在日志服务中查询请求日志、通过控制台查询结果、或提供给支持人员进行日志排查。
在控制台输入API网关所在Region
以及X-Ca-Request-Id
,点击查询,就可以看到对应的日志信息,如图
另外您也可以通过日志服务查看API调用日志,文档中有日志各字段具体的含义,可以帮助您更好的查看日志信息。
3、分析错误原因
- 如果客户端收到的应答中X-Ca-Error-Code头为空,则表示这次应答的HTTP应答码由后端服务产生,API网关透传了来自后端的错误信息,需要您重点排查后端服务,以及从API网关到后端服务之间的网络配置。
- 如果X-Ca-Error-Code头不为空,表示应答码由API网关产生,错误码由一个6位长度的字符描述
您可以根据
X-Ca-Error-Code
的6位错误码对比错误代码表来获取更详细的排错解释。