阿里云API网关（9）常见问题

网关指南： 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 提供者使用的证书其他非主流机构颁发的证书，此类证书使用浏览器访问是没有问题的，因为浏览器会自动更新根证书。但老版本操作系统的根证书对这些机构（证书颁发机构）的不信任或者信任时间已经过期。

解决方案

1. 升级客户端根证书。如：Java+Linux 升级 OpenSSL 客户端即可，其他操作系统+编程语言，请升级编程语言中 HTTPS 使用的根证书。
2. 联系 API 提供者，要求其更换兼容性更好的主流 SSL 证书。
3. 程序中忽略检查 SSL 证书有效性（不推荐），忽略后会有请求被劫持的安全风险。只在与 API 提供商无法提供兼容性更好的主流 SSL 证书，且安全风险可控的前提下，可以考虑使用此方法。

2. API提供者的 SSL 证书过期

提供者的 SSL 证书过期。

解决方案

1. 联系 API 提供者，要求其更换 SSL 证书。
2. 程序中忽略检查 SSL 证书有效性（不推荐），忽略后会有请求被劫持的安全风险。只在与 API 提供商无法提供兼容性更好的主流 SSL 证书，且安全风险可控的前提下，可以考虑使用此方法。

四、错误代码表

公共错误码

报错场景

错误码

错误提示

状态码

建议

Domain 不正确（通过 Domain 找不到 Product）。

InvalidProduct.NotFound

Cannot find product according to your specified domain.

404

请检查调用的域名或产品配置中的域名是否正确。

API 找不到
该 API 是 Private 类型，名单中没有该用户。

InvalidApi.NotFound

Specified api is not found,
please check your url and method.

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
due to some unknown error.

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、环境。

1. API 说明中要求用 POST 则不能用 GET 请求。Method 要一致。
2. Path 要与当前运行的一致。开放 API 的用户经常修改之后不发布，导致调用失败。
3. 指定环境要合理。在请求的 Header 里有个参数 X-Ca-Stage，取值 TEST/PRE/RELEASE，分别指向测试和线上环境，不传入该参数则默认是线上。
4. 更多参数及请求说明，参见 API 调用示例

七、Unauthorized

错误原因

请求 API 时，使用的 AppKey 所属于的 APP 未获得授权。无权调用 API。

解决方法

授权生效的决定因素有：APP、API、环境、已授权

1. 如果是开放 API 的用户自己测试，则需要在 API 网关控制台，真实创建 APP，然后根据 AppId 在 API 列表页操作授权。即开放 API 的用户自测时，其实是自己需要给自己创建的 APP 授权。
2. 如果是购买了 API 的用户，则在 APP 详情页可以查看该 APP 已经被授权的 API，若没有要调用的 API，则自行操作授权。
3. 如果是使用了合作伙伴的 API，没有购买行为的。则联系合作伙伴。您需要提供 AppId，然后由 API 提供者操作授权。
4. 授权关系是有环境属性的，即 APP、API都是同一个的情况下，授权的环境和请求的环境也要相同。授权了某 API 在 A 环境的权限，但是也不能调用该 API 在 B 环境中的服务。请求时的环境等参数指定，请参见【API请求示例】。
5. 最重要的一点是，确认清楚是否用错了 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段的区域需重复执行操作），添加时请注意内、外网。

区域

内网

外网

华北 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？

• 如何不中断服务更换后端密钥？

• 如何给指定人开放API？

• 对并发的限制是怎么样的？

十、API定义

• Path与后端服务地址中的动态参数名称、顺序是否必须保持一致？

• 为什么无法调通我的后端服务？

• 用户传了一个未定义的参数，网关将如何处理

• 后端服务是否可以使用HTTPS

• 服务信息是什么

• API基础定义是什么

• 为什么要填写API描述

• API类型是什么

• API名称是什么

• API更新是否会有延迟

• 一个分组最多可以绑定5个已备案的域名

• 如何使您的API支持HTTPS？

• 后端服务地址如何录入？

• 为什么要定义参数？

• 参数定义是必须的吗？

• 不定义参数网关如何处理？

• 参数定义包含什么？

• 可以对参数做哪些限制？

• Path是什么？

• 为什么会提示我Path冲突？

十一、产品说明

• VPC下的用户使用API网关有什么要求？

• 有没有节点、可用区的要求？

• 申请用户的资格是什么？账号下是否需要什么业务？

• 产品是否可以升级、降配，流程是什么？

• 产品使用是怎么收费的？

• 产品在控制台的管理都有什么？如何管理？

• 金融云和微金融用户可以购买么？

• 产品应用场景及作用

• 产品购买时长是什么？一个账号购买的有限制么？

• 这个产品可以使用安全产品吗？可以在slb上配置吗？

• 网关支持百倍赔偿吗？

• 支持退款吗，如何操作？

• 支持在线协议吗？如果是线下协议如何操作？

• 产品续费到期暂停时间、删除时间

十二、调用api

• APP是什么，怎么从用户实际的应用关联到我们定义的APP，实际应用是移动端还是web端？
• 移动端的AppKey安全怎么保障？
• 如何指定调用环境？
• 为什么API无法调用？
• 如何有效防止API的重放攻击？

十三、分组相关

• 我可以创建多少API分组？
• 云API部署在哪些地域？
• 该怎么选择分组地域？
• 二级域名是什么，有什么使用限制？

十一、产品说明

如何找到已购买的API

更新时间：2017-06-17 14:10:07   分享：   

您在API市场上购买API之后，即完成API的自动授权。您可以在管理控制台寻找您都已经购买的PI。

• 打开云市场，在右上角点击【买家中心】-【[进入管理控制台]】

(https://market.console.aliyun.com/imageconsole/index.htm “进入管理控制台”)

• 在左侧菜单，点击【API】即可，如图：

十四、监控与告警

• API监控的时效性
• API监控的维度
• 如何查看API的运行情况

十五、相关协议

阿里云API网关试用服务协议

十六、域名相关

• 域名绑定多久能生效？
• 如何使用一个自有域名访问API？
• 域名是不是需要在[阿里云](https://l.gushuji.site/aliyun)备案才能用于开放API？
• 如何解析域名？
• 分组可以绑定几个域名？

转载于:https://www.cnblogs.com/lexiaofei/p/7216208.html