网关指南: https://help.aliyun.com/document_detail/29487.html?spm=5176.doc48835.6.550.23Oqbl
网关控制台: https://apigateway.console.aliyun.com/?spm=5176.doc42740.2.2.Q4z5ws#/cn-hangzhou/apis/list
一、如何获取错误信息
所有的 API 请求只要到达了网关,网关就会返回请求结果信息。
用户需要查看返回结果的头部,即 Header 部分。其中 X-Ca开头的均为网关返回,比较重要信息是:
在 Header 中获得 X-Ca-Error-Message 可以基本明确报错原因,而 X-Ca-Request-Id 可以用于提供给这边的支持人员,供支持人员搜索日志。
二、返回值为空
HTTP/HTTPS 请求的返回结果有 HttpCode、Header、Body 三部分。当请求报错时,由于没有进入业务逻辑,所以返回的 Body 可能为空,表现为“返回值为空”,但实际上,重要信息都在 Header 里面。
用户发起的 API 请求只要能够到达网关,就会返回成功/错误的结果信息。
重要的返回信息都在Header里面,以X-Ca开头的为网关返回的信息。其中较主要的为下面的几个信息:
所以如果发送请求后,发现返回值为空,那么看一下返回的 Header 信息。如果请求到达网关就错误返回了,那么 Body 为空很正常,会表现为返回值为空,但是在 Header 里面会有重要信息。
如果Header也为空,那么说明请求没有达到网关,请自行检查网络状况等。
各种语言获取和查看 HTTP/HTTPS 头部信息的方法均可在网上查询到。
三、HTTPS证书报错
错误提示
调用 HTTPS 接口出现证书认证错误或者提示证书已经过期。
原因及解决方案
1. 证书不合法
API 提供者使用的证书其他非主流机构颁发的证书,此类证书使用浏览器访问是没有问题的,因为浏览器会自动更新根证书。但老版本操作系统的根证书对这些机构(证书颁发机构)的不信任或者信任时间已经过期。
解决方案
- 升级客户端根证书。如:Java+Linux 升级 OpenSSL 客户端即可,其他操作系统+编程语言,请升级编程语言中 HTTPS 使用的根证书。
- 联系 API 提供者,要求其更换兼容性更好的主流 SSL 证书。
- 程序中忽略检查 SSL 证书有效性(不推荐),忽略后会有请求被劫持的安全风险。只在与 API 提供商无法提供兼容性更好的主流 SSL 证书,且安全风险可控的前提下,可以考虑使用此方法。
2. API提供者的 SSL 证书过期
提供者的 SSL 证书过期。
解决方案
- 联系 API 提供者,要求其更换 SSL 证书。
- 程序中忽略检查 SSL 证书有效性(不推荐),忽略后会有请求被劫持的安全风险。只在与 API 提供商无法提供兼容性更好的主流 SSL 证书,且安全风险可控的前提下,可以考虑使用此方法。
四、错误代码表
公共错误码
报错场景 |
错误码 |
错误提示 |
状态码 |
建议 |
---|---|---|---|---|
Domain 不正确(通过 Domain 找不到 Product)。 |
InvalidProduct.NotFound |
Cannot find product according to your specified domain. |
404 |
请检查调用的域名或产品配置中的域名是否正确。 |
API 找不到 |
InvalidApi.NotFound |
Specified api is not found, |
404 |
请检查调用的 API 是否正确,需注意大小写,确认是否配置了访问控制。 |
API 必须使用 HTTPS 协议。 |
InvalidProtocol.NeedSsl |
Your request is denied as lack of ssl protect. |
400 |
请检查 API 配置,是否配置成只支持 https。 |
必填参数没有填({}中替换成相应的参数名)。 |
Missing{ParameterName} |
{ParameterName} is mandatory for this action. |
400 |
检查调用时是否填写提示的了此参数。 |
AccessKeyId 找不到 |
InvalidAccessKeyId.NotFound |
Specified access key is not found. |
404 |
请检查调用时是否使用了正确的 AccessKeyId。 |
AccessKeyId 被禁用。 |
InvalidAccessKeyId.Inactive |
Specified access key is disabled. |
400 |
检查 AK 是否可用,或是否与所在环境匹配。 |
时间戳格式不对( Date 和 Timestamp) |
InvalidTimeStamp.Format |
Specified time stamp or date value is not well formatted. |
400 |
检查时间戳 |
用户时间和服务器时间不在15分钟内 |
InvalidTimeStamp.Expired |
Specified time stamp or date value is expired. |
400 |
检查时间戳 |
SignatureNonce 重复 |
SignatureNonceUsed |
Specified signature nonce war used already. |
400 |
|
MD5 校验不通过(ROA) |
ContentMD5NotMatched |
Specified content md5 is not matched with your request body. |
400 |
|
返回值格式不正确( Format 不支持) |
InvalidParameter.Format |
Specified parameter format is not valid. |
400 |
支持 XML/JSON,ROA 方式支持 application/json、application/xml。 |
返回值格式不正确(Accept 不支持) |
InvalidParameter.Accept |
Specified parameter accept is not valid. |
400 |
|
参数值校验不通过 |
Invalid{ParameterName} |
Specified parameter {ParameterName} is not valid. |
400 |
|
Http 请求方法不支持( API 上回配置允许的请求方法) |
UnsupportedHTTPMethod |
Specified signature is not matched with our calculation. |
400 |
|
签名方法不支持 |
InvalidSignatureMethod |
Specified signature method is not valid. |
400 |
|
服务器端位置错误 |
InternalError |
The request processing has failed |
500 |
|
服务暂时不可用(底层服务不可用) |
ServiceUnavailable |
The request has failed due to a temporary failure of the server. |
503 |
建议检查 API 配置中的 Isp 协议描述,并检查接入方提供的服务是否正常 |
签名不通过 |
SignatureDoesNotMatch |
Specified signature is not matched with our calculation. |
400 |
签名不通过,请参照 签名验证 |
参数取值不匹配(url和body体中的参数不匹配) |