网关指南： 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体中的参数不匹配） |
ValueMismatch.{ParameterName} |
Multi-specified parameter {ParameterName} conflicts with each other. |
400 |
|
|
用户这个时段的流量已经超限 |
Throttling.User |
Request was denied due to user flow control. |
||
|
API 这个时段的流量已经超限 |
Throttling.API |
Request was denied due to api flow control. |
||
|
指定的 content-length 与 body 长度不匹配 |
ContentLengthDoesNotMatch |
Specified content-length is not matched with the length of body. |
400 |
|
|
指定的参数重复 |
RepeatedParameter. {ParameterName} |
Specified parameter is repeated. |
400 |
|
|
用户这个时段的流量已经超限 |
Throttling.User |
Request was denied due to user flow control. |
400 |
|
|
API 这个时段的流量已经超限 |
Throttling.API |
Request was denied due to api flow control. |
400 |
|
|
缺少AccessKeyId |
MissingSecurityToken |
SecurityToken is mandatory for this action. |
400 |
当 AccessKeyId 以 STS. 开头时，走 Token 的鉴权逻辑。如果 AccessKeyId 以 STS. 但未提供 SecurityToken 参数(包括 RPC 和 ROA)时报此错误 |
|
SecurityToken 过期 |
InvalidSecurityToken.Expired |
Specified SecurityToken is expired. |
400 |
需检查 SecurityToken |
客户端错误（开放 API ）
| 错误代码 | 描述 | Http 状态码 | 语义 | 解决方案 |
|---|---|---|---|---|
| Repeated%s | The specified %s is repeated. | 400 | 某参数重复（%s 是占位符，实际调用会给出明确的参数名或提示。） | 建议按照提示修改重复的参数后重试。 |
| RepeatedCommit | Resubmit request. | 400 | 请求重复 | 请不要频繁提交请求。 |
| Missing%s | The %s is mandatory for this action. | 400 | 缺少参数 %s | 根据具体返回补充缺少的参数，重试请求。 |
| MissingAppIdOrAppOwner | AppId or AppOwner must have a valid value. | 400 | 缺少参数 AppId 或者 AppOwner | 参数 AppId 和 AppOwner 不能同时为空。 |
| Invalid%s | The specified parameter %s value is not valid. | 400 | 参数无效 | 根据返回提示的具体参数，查看相关参数约束，修改后重试。 |
| NotFound%s | Cannot find resource according to your specified %s. | 400 | 找不到资源 | 根据指定的参数%s找不到资源，建议检查%s是否正确。 |
| InvalidFormat%s | The specified parameter %s value is not well formatted. | 400 | 参数格式错误 | 建议根据实际返回提示，查看%s的格式要求，修改后重试。 |
| Duplicate%s | The specified parameter %s value is duplicate. | 400 | 参数重复 | 某请求参数不允许重复，建议检查修正后重试。 |
| DependencyViolation%s | The specified %s has %s definitions. | 400 | 参数依赖错误 | 指定参数被依赖，不能随意删除，请先解除依赖。 |
| Forbidden%s | Not allowed to operate on the specified %s. | 403 | 无权操作/操作禁止 | 您无权执行该操作。 |
| NoPermission | User is not authorized to operate on the specified resource. | 403 | 无权操作 | RAM 鉴权不通过。 |
| ExceedLimit%s | The specified %s count exceeds the limit. | 400 | 超出个数限制 | 一般指用户账户下创建的 API、API 分组或者APP超出个数限制。 |
| UserNotFound | The specified user can not be found. | 404 | 指定用户找不到 | 根据输入的用户信息找不到该用户。 |
| DomainCertificateNotFound | Cannot find the domain certificate. | 400 | 指定域名证书不存在 | 建议检查传入的证书 ID 及名称。 |
| DomainNotResolved | The specified domain has not been resolved. | 400 | 指定域名未解析 | 需要将指定域名 CNAME 解析到分组的二级域名上，才能完成绑定。域名解析是在用户域名购买的网站上操作。 |
| InvalidICPLicense | The specified domain have not got ICP license, or the ICP license does not belong to Aliyun. | 400 | 域名备案不合格 | 要绑定的域名需要在阿里云做首次备案，已经在其他系统做备案的，需要在阿里云备案接入。备案接入需要获取备案号，在阿里云有 ECS 且具有公网 IP 的，每个 ECS 有5个备案号。 |
| Invalid%s.LengthLimit | The parameter %s length exceeds the limit. | 400 | 长度超限 | 参数%s超出长度限制，建议修正后重试。 |
| InvalidApiDefault | The ApiDefault value exceeds limit. | 400 | 流控 API 默认值超过限制值 | 该值数值不能超过1亿，与单位无关。如需上调请提工单申请。 |
| InvalidAppDefault | The AppDefault value must smaller than the UserDefault and ApiDefault. | 400 | AppDefault 的值不符合规则 | 该值需要小于 API 流控值和用户流控值。 |
| InvalidUserDefault | The UserDefault value must bigger than the AppDefault and smaller than the ApiDefault. | 400 | UserDefault 的值不符合规则 | 该值需要小于 API 流控值并大于 APP 流控值。 |
| InvalidParamMapping | Parameters must be fully mapped. | 400 | 参数映射无效 | 创建 API 时，前后端参数映射需要是全映射。即每个入参都需要配置后端参数名称。 |
| InvalidOwnerAccount | OwnerAccount is invalid. | 400 | APP所有者账号无效 | 一般为操作授权时，输入目标用户的阿里云邮箱账号，该账号无效。建议检查修正后重试。 |
| ServiceForbidden | Your Gateway service is forbidden by risk control. | 400 | API 网关服务被风控（应该使用户被风控吧） | 请注意不要频繁请求，建议稍后重试。若重试后仍未解决，可提工单咨询。 |
| ServiceUnOpen | Your Gateway service has not been opened. | 400 | 服务未开通 | 建议到阿里云官网开通一下 API 网关服务。 |
| ServiceInDept | Your API Gateway service is in dept. | 400 | （您的 API 网关）服务欠费 | 充值或者结算后重新开始使用。 |
| EqualSignature | The new signature is the same as the old. | 400 | 新密钥与旧的相等 | 修改后端签名密钥时，新设置的 Key 和 Secret 不能跟原来的一样。 |
| CertificateNotMatch | The domain does not match the one in the certificate. | 400 | 证书不匹配 | 指定域名与证书内域名不匹配。 |
| CertificateKeyNotMatch | The certificate private key does not match the public key. | 400 | 证书密钥不匹配 | 证书的公钥和私钥不匹配。 |
| PrivateKeyEncrypted | The certificate private key is encrypted, please upload the unencrypted version. | 400 | 密钥不能加密 | 证书私钥加密了，要求上传不加密的版本。 |
| CertificateSecretKeyError | The certificate private key is invalid. | 400 | 证书私钥错误 | 建议检查后重新传入。 |
| InvalidApiServiceAddress | The specified service address is not valid. | 400 | API 后端服务地址无效 | 配置的 API 后端服务地址无效。 |
客户端错误（调用 API ）
| 错误代码 | Http 状态码 | 语义 | 解决方案 |
|---|---|---|---|
| Throttled by USER Flow Control | 403 | 因用户流控被限制 | 一般是由于 API 服务商设置的用户流控值导致被流控，可以联系 API 服务商协商放宽限制。 |
| Throttled by APP Flow Control | 403 | 因APP流控被限制 | 一般是由于 API 服务商设置的 APP 流控值导致被流控，可以联系 API 服务商协商放宽限制。 |
| Throttled by API Flow Control | 403 | 因 API 流控被限制 | 一般是由于 API 服务商设置的 API 流控值导致被流控，可以联系 API 服务商协商放宽限制。 |
| Throttled by DOMAIN Flow Control | 403 | 因二级域名流控被限制 | 直接访问二级域名调用 API，每天被访问次数上限1000次。 |
| TThrottled by GROUP Flow Control | 403 | 因分组流控被限制 | 每个分组有 QPS 限制，可以联系 API 服务商反馈。 |
| Quota Exhausted | 403 | 调用次数已用完 | 购买的次数已用完。 |
| Quota Expired | 403 | 购买次数已过期 | 购买的次数已经过期。 |
| User Arrears | 403 | 用户已欠费 | 请尽快充值续费。 |
| Empty Request Body | 400 | body 为空 | 请检查请求 Body 内容。 |
| Invalid Request Body | 400 | body 无效 | 请检查请求 Body。 |
| Invalid Param Location | 400 | 参数位置错误 | 请求参数位置错误。 |
| Unsupported Multipart | 400 | 不支持上传 | 不支持上传文件。 |
| Invalid Url | 400 | Url 无效 | 请求的 Method、Path 或者环境不对。请参照错误说明 Invalid Url。 |
| Invalid Domain | 400 | 域名无效 | 请求域名无效，根据域名找不到 API。请联系 API 服务商。 |
| Invalid HttpMethod | 400 | HttpMethod 无效 | 输入的 Method 不合法。 |
| Invalid AppKey | 400 | AppKey 无效或不存在 | 请检查传入的 AppKey。注意左右空格的影响。 |
| Invalid AppSecret | 400 | APP 的Secret 错误 | 检查传入的 AppSecret。注意左右空格的影响。 |
| Timestamp Expired | 400 | 时间戳过时 | 请核对请求系统时间是否为标准时间。 |
| Invalid Timestamp | 400 | 时间戳不合法 | 请参照 请求签名说明文档。 |
| Empty Signature | 404 | 签名为空 | 请传入签名字符串，请参照 请求签名说明文档。 |
| Invalid Signature, Server StringToSign:%s | 400 | 签名无效 | 签名无效，参照 Invalid Signature 错误说明 |
| Invalid Content-MD5 | 400 | Content-MD5 值不合法 | 请求 Body 为空，但传入了 MD5 值，或 MD5 值计算错误。请参照 请求签名说明文档。 |
| Unauthorized | 403 | 未被授权 | APP 未获得要调用的 API 的授权。请参照错误说明 Unauthorized。 |
| Nonce Used | 400 | SignatureNonce 已被使用一次 | SignatureNonce 不能被重复使用。 |
| API Not Found | 400 | 找不到 API | 传入的 GroupId、Stage 等参数不正确，或已下线。 |
服务器端错误（开放 API ）
| 错误代码 | 描述 | Http 状态码 | 语义 | 解决方案 |
|---|---|---|---|---|
| ServiceUnavailable | The request has failed due to a temporary failure of the server. | 503 | 服务不可用 | 建议重试。 |
| InternalError | The request processing has failed due to some unknown error, exception or failure. | 500 | 内部错误 | 建议重试。 |
服务器端错误（调用 API）
| 错误代码 | Http 状态码 | 语义 | 解决方案 |
|---|---|---|---|
| Internal Error | 500 | API 网关内部错误 | 建议重试。 |
| Failed To Invoke Backend Service | 500 | 底层服务错误 | API 提供者底层服务错误，建议重试，如果重试多次仍然不可用，可联系 API 服务商解决。 |
| Service Unavailable | 503 | 服务不可用 | 建议稍后重试。 |
| Async Service | 504 | 后端服务超时 | 建议稍后重试。 |
五、Invalid Signature
错误原因
客户端与服务端计算的签名不匹配导致的。
解决方案
当签名不匹配时网关会通过 HTTP Response Header 中的 X-Ca-Error-Message 返回服务端参与签名计算的 StringToSign。
StringToSign是用户请求前需要拼接的一个用于计算签名的字符串，在文档：【请求签名说明文档】查看详细说明。
客户端只需打印出本地自己拼接的 StringToSign 进行对比，找出哪里不同，针对性的解决，如果使用的官方提供的调用 Demo，可以到签名计算的工具类中找出计算签名前的 StringToSign 打印出来即可进行对比。
因为 HTTP Response Header 中不允许出现换行符，因此返回结果中的 StringToSign 换行符都已经被抹去。请参照文档合理比对。
如果服务端 StringToSign 与客户端一致，请再检查使用的 AppKey、AppSecret 是否正确，尤其注意是否额外错误添加了空格等不容易发现的字符。
六、Invalid Signature
错误原因
请求传入的 HTTP Method 或者 Path 不正确，或者请求指定的环境（X-Ca-Stage）不正确。
如指定调用 TEST 环境的 API，但 API 并未被发布到测试。
注意：
- 请求时不指定环境，默认为访问 RELEASE 环境。
- 对 API 定义有修改，需要重新发布才能生效。许多出现这个错误的都是因为修改了 Path 没发布不生效，用新 Path 请求报错。
解决办法
分别检查上述三个因素：HTTP Method、Path、环境。
- API 说明中要求用 POST 则不能用 GET 请求。Method 要一致。
- Path 要与当前运行的一致。开放 API 的用户经常修改之后不发布，导致调用失败。
- 指定环境要合理。在请求的 Header 里有个参数 X-Ca-Stage，取值 TEST/PRE/RELEASE，分别指向测试和线上环境，不传入该参数则默认是线上。
- 更多参数及请求说明，参见 API 调用示例
七、Unauthorized
请求 API 时，使用的 AppKey 所属于的 APP 未获得授权。无权调用 API。
解决方法
授权生效的决定因素有：APP、API、环境、已授权
- 如果是开放 API 的用户自己测试，则需要在 API 网关控制台，真实创建 APP，然后根据 AppId 在 API 列表页操作授权。即开放 API 的用户自测时，其实是自己需要给自己创建的 APP 授权。
- 如果是购买了 API 的用户，则在 APP 详情页可以查看该 APP 已经被授权的 API，若没有要调用的 API，则自行操作授权。
- 如果是使用了合作伙伴的 API，没有购买行为的。则联系合作伙伴。您需要提供 AppId，然后由 API 提供者操作授权。
- 授权关系是有环境属性的，即 APP、API都是同一个的情况下，授权的环境和请求的环境也要相同。授权了某 API 在 A 环境的权限，但是也不能调用该 API 在 B 环境中的服务。请求时的环境等参数指定，请参见【API请求示例】。
- 最重要的一点是，确认清楚是否用错了 APP，是否调用错了 API。由于 API 和 APP 较多，很多用户因为搞混了而没能调用成功。比如授权了 APP A，但是调用时候用的是 APP B，请仔细排查。
八、后端服务调不通
- 需要检查您录入的后端服务地址是否正确。
- 需要保证您的后端服务可以被网关访问到。
- 如果使用的是内网 IP ，请保证您的后端服务于您的 API 处于同一地域。
-
检查您API定义的“后端超时”时间。
在API定义时会要求您录入一个超时时间，当您的后端服务没有在您指定的时间内返回时，API网关仍然会提示您无法链接后端服务。您可以根据后端服务的实际耗时对”后端超时”进行调整，最大支持30000ms。注意：单位是ms（毫秒）
- 如后端服务在 Ecs ，请检查安全组设置，是否可以被外部访问。请保证安全组可以被API网关所在的IP段访问。
- 设置方法点击链接：设置ECS安全组
跳转至：
在发送调用请求前，请调整如下配置项，其他项为选填，如无特殊要求，请不要改动。- RegionId,区域ID，请填写资源所在的区域ID,例如：cn-shenzhen、cn-shanghai
- PortRange：端口，若后端服务HTTP为：80/80，HTTPS：443/443
- NicType：网络类型，取值：
- internet：外网
- intranet：内网
- 若以如上述链接进入，则已经为您默认设置了：intranet（内网）
- SourceCidrIp:允许的源IP地址范围，以下地址为API网关的出口IP，请区分区域填写
注：部分区域的API网关存在多个出口IP段，均需要加入安全组（每次操作只能添加一个IP段，多个IP段的区域需重复执行操作），添加时请注意内、外网。
- 设置方法点击链接：设置ECS安全组
| 区域 | 内网 | 外网 |
| 华北 1（青岛） | 10.151.203.0/24 | |
| 华北 2（北京） | 10.152.167.0/24 | 123.56.213.0/24 |
| 华南 1（深圳） | 10.152.27.0/24 | 120.76.91.0/24 |
| 华东 1（杭州） | 10.152.29.0/24 10.152.30.0/24 |
114.55.70.0/24 |
| 华东 2（上海） | 10.152.163.0/24 10.152.164.0/24 11.192.97.0/24 11.192.98.0/24 11.192.96.0/24 |
139.224.92.0/24 139.224.92.0/24 139.224.4.0/24 |
| 香港 | 10.152.161.0/24 10.152.162.0/24 |
47.91.171.0/24 47.89.61.0/24 |
| 亚太东南 1（新加坡） | 10.152.165.0/24 10.152.166.0/24 11.192.152.0/23 11.193.8.0/24 11.193.9.0/24 |
47.88.235.0/24 47.88.147.0/24 |
- 填写完成后，点击发送请求 ，完成设置。
当之返回一个RequestID时，表示设置成功
确认添加是否成功
可以到控制台-【ECS控制台】-【安全组】-找到相应安全组，点击查看“安全组规则”的“内网入方向”或者“公网入方向”。
- 填写完成后，点击发送请求 ，完成设置。
九、api安全
十、API定义
- 为什么无法调通我的后端服务？
- 用户传了一个未定义的参数，网关将如何处理
- 后端服务是否可以使用HTTPS
- 服务信息是什么
- API基础定义是什么
- 为什么要填写API描述
- API类型是什么
- API名称是什么
- API更新是否会有延迟
- 一个分组最多可以绑定5个已备案的域名
- 如何使您的API支持HTTPS？
- 后端服务地址如何录入？
- 为什么要定义参数？
- 参数定义是必须的吗？
- 不定义参数网关如何处理？
- 参数定义包含什么？
- 可以对参数做哪些限制？
- Path是什么？
- 为什么会提示我Path冲突？
十一、产品说明
十二、调用api
- APP是什么，怎么从用户实际的应用关联到我们定义的APP，实际应用是移动端还是web端？
- 移动端的AppKey安全怎么保障？
- 如何指定调用环境？
- 为什么API无法调用？
- 如何有效防止API的重放攻击？
十三、分组相关
十一、产品说明
如何找到已购买的API
更新时间：2017-06-17 14:10:07 分享：
您在API市场上购买API之后，即完成API的自动授权。您可以在管理控制台寻找您都已经购买的PI。
- 打开云市场，在右上角点击【买家中心】-【[进入管理控制台]】
(https://market.console.aliyun.com/imageconsole/index.htm “进入管理控制台”)
- 在左侧菜单，点击【API】即可，如图：
