阿里雲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

更新時間:2017-06-17 14:10:07   分享:   

您在API市場上購買API之后,即完成API的自動授權。您可以在管理控制台尋找您都已經購買的PI。

  • 打開雲市場,在右上角點擊【買家中心】-【[進入管理控制台]】

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

  • 在左側菜單,點擊【API】即可,如圖:

API

十四、監控與告警

十五、相關協議

阿里雲API網關試用服務協議

十六、域名相關

 

 


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM