返回参数
字段名 | 中文 | 类型 | 返回条件 | 说明 |
---|---|---|---|---|
apid | 接口ID | string | 必有返回 | 网关发送API请求的ID,同header["X-Ca-Request-Id"] |
apis | 接口名称 | string | 必有返回 | API请求名 |
fault | 瑕疵次数 | int | 必有返回 | 接口发生瑕疵的次数,本字段值计入数据库,并不显式给客户端,用于提示平台开发者,API的健康状况。 |
status | 网络返回 | int | int | http请求的标准网络返回 |
error | 错误码 | int | int | 错误码 |
reason | 错误理由 | string | string | 错误理由(英文) |
message | 错误说明 | string | string | 错误说明,支持多国语言,用于在客户端显示错误信息。 |
result | 返回结果 | dict | dict | 返回的结果字典(不能是字符串,数组)。 |
debug | 返回调试 | dict | 令牌bug=1 | 返回的调试字典(不能是字符串,数组)。 |
trace | 堆栈信息 | dict | 令牌bug=T | 返回数组形式的堆栈。 |
event | 请求事件 | dict | 令牌bug=1 | 返回的请求事件 |
如何获取错误信息
所有的 API 请求只要到达了网关,网关就会返回请求结果信息。 用户需要查看返回结果的头部,即 Header 部分。其中 X-Ca开头的均为网关返回,比较重要信息是:
// 请求唯一ID,请求一旦进入API网关应用后,API网关就会生成请求ID并通过响应头返回给客户端,建议客户端与后端服务都记录此请求ID,可用于问题排查与跟踪
X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF
// API网关返回的错误消息,当请求出现错误时API网关会通过响应头将错误消息返回给客户端
X-Ca-Error-Message: Invalid Parameter Required `field1`
// API网关系统错误码,当请求出现错误被网关拦截后,由API网关提供的错误码:(经典网络实例无此头)
X-Ca-Error-Code: I400MP
在应答的Header中获得X-Ca-Error-Code与X-Ca-Error-Message可以基本明确报错原因,而X-Ca-Request-Id可以用于在日志服务中查询请求日志、通过控制台查询结果、或提供给支持人员进行日志排查。
X-Ca-Error-Code可以查找错误代码表来获取更详细的拍错解释。
当返回值(body字段)为空
HTTP/HTTPS 请求的返回结果有 HttpCode、Header、Body 三部分。当请求报错时,由于没有进入业务逻辑,所以返回的 Body 可能为空,表现为“返回值为空”,但实际上,重要信息都在 Header 里面。
用户发起的 API 请求只要能够到达网关,就会返回成功/错误的结果信息。
重要的返回信息都在Header里面,以X-Ca开头的为网关返回的信息。其中较主要的为下面的几个信息:
X-Ca-Request-Id: 7AD052CB-EE8B-4DFD-BBAF-EFB340E0A5AF
//请求唯一ID,请求一旦进入API网关应用后,API网关就会生成请求ID并通过响应头返回给客户端,建议客户端与后端服务都记录此请求ID,可用于问题排查与跟踪
X-Ca-Error-Message: Invalid Url
//API网关返回的错误消息,当请求出现错误时API网关会通过响应头将错误消息返回给客户端
X-Ca-Debug-Info: {"ServiceLatency":0,"TotalLatency":2}
//当打开Debug模式后会返回Debug信息,此信息后期可能会有变更,仅用做联调阶段参考
所以如果发送请求后,发现返回值为空,那么看一下返回的 Header 信息。如果请求到达网关就错误返回了,那么 Body 为空很正常,会表现为返回值为空,但是在 Header 里面会有重要信息。 如果Header也为空,那么说明请求没有达到网关,请自行检查网络状况等。 各种语言获取和查看 HTTP/HTTPS 头部信息的方法均可在网上查询到。