網關指南: 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】即可,如圖:
十四、監控與告警
十五、相關協議
十六、域名相關