API異常排查方法
一、快速追蹤問題
1、快速追蹤問題流程圖
附：API文件位址：//open.taobao.com/api/api_list.htm?spm=a219a.7386781.0.0.g5ZY6Y
#規則中心網址：//open.taobao.com/doc/detail.htm?id=101612
淘寶客服聯絡方式：http://www.taobao.com/about/contact.php
API測試工具位址：http://my.open.taobao.com/apitools/apiTools.htm
錯誤碼一覽網址：//open.taobao.com/doc/detail.htm ?id=101645
論壇網址：//open.taobao.com/bbs/forum.php
常見技術問題網址：//open.taobao.com/doc/detail.htm ?id=101783
支援中心位址：//open.taobao.com/support/index.htm?spm=a219a.7386781.0.0.r8QQcW
#緊急問題旺旺群：228708748
流程圖中問題詳解
非API問題
開發者發送HTTP請求淘寶資料之前的出現的問題，包括淘寶業務問題，商務問題，容器類別錯誤問題。
1. 淘寶業務問題：
（1）業務規則問題，例如：商品或用戶被處罰等
（2）在淘寶頁面操作不成功的問題，例如：在淘寶後台無法查看出售中的商品等
2. 商務問題：
（1）應用接入問題，例如：一個開發者可以註冊多少個應用程式等
（2）應用審核問題，例如：哪些應用程式不支援存取等
（3）應用上線問題，例如：呼叫頻率是如何限制的等
#3 . 容器類別錯誤問題：
透過容器，使用者可以授權開發者取得其資料訊息，主要是頁面上錯誤碼在100到200之間的錯誤。
API問題
開發者發送HTTP請求淘寶資料之後的出現的問題，包括HTTP連接錯誤問題，平台級錯誤問題，業務級錯誤問題，這三種類型的錯誤問題分別是在存取淘寶伺服器，TOP接取平台，淘寶後端業務伺服器這三個層次上出現的問題。
1. HTTP連線錯誤問題：
請求淘寶伺服器過程中出現的錯誤，這類型錯誤通常由HTTP回應碼標記出來，HTTP回應碼由三位十進位數字組成，它們出現在由HTTP伺服器發送的回應的第一行。回應碼分成五種類型，由它們的第一位數字表示：
1xx：訊息，請求收到，繼續處理
2xx：成功，行為被成功地接受、理解和採納
3xx：重定向，為了完成請求，必須進一步執行的動作
4xx：客戶端錯誤，請求包含語法錯誤或請求無法實現
5xx：伺服器錯誤，伺服器不能實現一種明顯無效的請求
開發者呼叫TOP服務最常收到就是200：http請求成功；404：未找到請求的服務；500內部伺服器錯誤等。如果開發者收到的回應碼是404，表示使用者的網路有問題，如果開發者收到的回應碼是回應碼是500，表示網路是正常的但是top的服務無法回應。
如果是本地網路有問題可以直接輸入命令列ping gw.api.taobao.com測試請求淘寶伺服器的速度，如果速度很慢則要考慮伺服器提速的問題，如果ping不通，則聯繫網路管理員確認伺服器是否屏蔽淘寶網域。
2.平台級錯誤問題：
請求TOP接入平台出現的錯，此時TOP返回的錯誤碼小於100，這種錯誤一般是由於用戶的請求不符合權限，安全，流量和最基本的參數等校驗引起的。
3. 業務級錯誤問題：
請求後端業務伺服器出現的問題，回傳的錯誤碼在500到1000之間，具體子錯誤碼及解決方案可參考API文件。
2、檢查問題詳細流程圖
#詳細描述開發者發現以上問題之後的處理流程。 
#3、快速追蹤問題範例
#範例1我從錯誤日誌分析出來taobao.item.recommend.add報isv.item-recommend-service- error:ERROR_MORE_THAN_ALLOWED_RECOMMEND_NUM（超過櫥窗推薦總數）錯誤很多，該如何解決總數呢？ 首先根據排查問題流程定位到API問題，再查看API文件中的錯誤碼解決方案：1. 櫥窗推薦的時候要求用戶輸入櫥窗推薦總量，有的用戶會多輸，所以報櫥窗推薦超過最大建議數的錯誤，每天定時更新櫥窗總量，櫥窗總量=已推薦櫥窗剩餘櫥窗（不能完全杜絕這個錯誤）2. 開發者先調用taobao.shop.remainshowcase.get 介面取得賣家的剩餘櫥窗數，做好邏輯判斷，再呼叫櫥窗推薦的介面。
範例2
本地程式封包連線重置錯誤且沒有top的錯誤碼返回，這類問題該如何解決？ 建議：1.合理切割任務，將任務粒度放小，減少事務時間，提高事務執行成功率，降低迴滾代價;#2.合併任務中重複的內容，在時間間隔容許的範圍內，減少可能重複的操作;3.看是否有批量操作接口，減少單個循環調用次數;4.控制工作執行緒池執行緒個數，依照實際效能和對方伺服器處理能力設定並行任務個數：
執行緒並發開的越多未必成功率越高！ 首先本地資源有限（開的越多線程，本地GC回收頻率越高，影響執行速度，效率反而降低）；其次，對方可能會由於你的ip連線數過多主動拒絕連線；（DOS保護）再次，頻道無法重複使用。 （目前1.6JDK版本已經能夠較好的複用TCP頻道，並發瞬間開大量的TCP頻道本身就是一種損耗，有時候部分串列化，某種程度上會減少產生TCP頻道的數目合理利用頻道，提高效率和成功率，客戶端做好流控也很重要）###### ##########範例3#########網路丟包問題解決方案：# #####問題背景：######1.由於互聯網實體線路可靠性不是100%，ISV伺服器到TOP之間的通訊存在資料遺失情況######2.開發者需要一種方法來驗證每次存取取得的資料是不是完整的，有沒有丟包###3.目前有的ISV透過這樣的方法校驗完整性：連續多次呼叫API，並比較傳回結果，若完全相同，則認為是完整的。這種方法不可靠（多次呼叫本來就有可能回傳不同的業務結果），增加了ISV開發成本，也加重了TOP的伺服器壓力
解決方案：
為了解決開發者回饋的ISV校驗資料完整性的問題，TOP已經在HTTP Header中加入一個新的元素：top-bodylength。
使用方法：開發者取到這個top-bodylength的值，計算一下收到的HTTP Body長度，如果兩者相等，則表示傳回的資料是完整的，如果計算出HTTP Body的長度小於top-bodylength的值，表示發生了丟包。
附註：
1：TOP沒有改變HTTP Body，所以，不會對現有應用造成任何影響。
2：top-bodylength是表示HTTP Body的個String字元長度（不區分中文英文，都算1個長度）
二、錯誤碼一覽表
1.目前開發者呼叫API可能出現的錯誤有三類：API平台錯誤、ISV業務錯誤、容器類別錯誤。以下介紹一下和ISV成功率有關的名詞說明：
有效訪問量=成功訪問量ISV業務錯誤（成功存取指的是正常取得到資料且無報錯的呼叫）
ISV成功率=成功訪問量/有效訪問量
#2.連接淘寶伺服器錯誤主要是http連線錯誤或連線被重置被拒絕等，這類錯誤是開發者存取淘寶伺服器出現的問題，請直接聯絡伺服器管理員或透過網路搜尋答案。
1、API平台錯誤
#API平台錯誤是主要包含兩類錯誤：
#（1）錯誤碼小於100(不包含15,40,41錯誤碼)的呼叫錯誤，這種錯誤一般是由於使用者的請求不符合各種基本校驗而引起的。使用者遇到這些錯誤的傳回先檢查應用的權限、頻率等情況，然後參考文件檢驗一下傳入的參數是否完整且合法。
（2）子錯誤碼（sub_code）是"isp."開頭的呼叫錯誤，這種錯誤一般是由於服務端異常所造成的。使用者遇到這類錯誤需要每隔一段時間重試就可以解決。
錯誤碼小於100的平台級錯誤
| 錯誤碼錯誤描述-英文錯誤描述-中文解決方案3Upload Fail圖片上傳失敗將傳入的圖片格式改為正確的格式、適當的大小的圖片放進消息體裡面傳輸過來，如果傳輸仍然失敗需要減小圖片大小或者增加網絡頻寬進行嘗試7App Call Limited應用調用次數超限，包含調用頻率超限調整程序合理調用API，等限頻時間過了再調用，淘客的呼叫頻率是系統依照上個月交易額自動修改的，修改後的頻率會在官方論壇首頁以公告形式通知，開發者可自行查看9Http Action Not AllowedHTTP方法被禁止請用大寫的POST或GET，如果有圖片等資訊傳入則一定要用POST才可以10Service Currently Unavailable服務不可用多數是由未知異常引起的，仔細檢查傳入的參數是否符合文檔描述11Insufficient ISV Permissions開發者權限不足子錯誤碼目前有isv.permission-api-package-empty 沒有和任何存取包關聯，建議根據業務規則申請對應的權限isv.permission-api-package-not-allowed 不允許訪問不可訪問群組的API，建議檢查一下自己申請的應用標籤是否正確，如果確實需要訪問不可訪問組的API需要根據業務規則到對應的業務線申請權限例如：買家不可訪問組就會有一些訂單API不允許買家應用訪問isv.permission- api-package-limit 關聯的包中不允許訪問該API，建議根據業務規則申請對應的權限isv.permission-ip-whitelist-limit IP限制不允許訪問，建議到安全中心配置正確的IP白名單isv. permission-api-widget-only-limit 僅允許widget（組件）方式存取12Insufficient User Permissions用戶權限不足應用沒有權限調用增值權限的接口，可在淘寶合作夥伴後台提交權限申請13Insufficient Partner Permissions合作夥伴權限不足應用沒有沒有合作夥伴權限權限調用增值權限的接口，可在淘寶合作夥伴後台提交權限申請21Missing Method缺少方法名參數傳入的參數加入method字段22Invalid Method不存在的方法名傳入的method字段必需是你所調用的API的名稱，並且該API是確實存在的23Invalid Format無效資料格式傳入的format必需為json或xml中的一種24Missing Signature缺少簽名參數傳入的參數中必需包含sign字段25Invalid Signature無效簽名簽名必需根據正確的算法算出來的。演算法請見：//open.taobao.com/doc/detail.htm?id=101617#ss226Missing Session缺少SessionKey參數傳入的參數中必要包含session字段27Invalid Session 、 unmix-sessionkey-failure無效的SessionKey參數傳入的session必需是用戶綁定session拿到的，如果報session不合法可能是用戶沒有綁定session或session過期造成的，用戶需要重新綁定一下然後傳入新的sessionKey28Missing App Key缺少AppKey參數傳入的參數必要包含app_key欄位29Invalid App Key無效的AppKey參數應用程式所處的環境跟所選的環境不一致，例如：應用程式處於沙箱測試環境，卻選擇在正式環境進行測試。 30Missing Timestamp缺少時間戳參數傳入的參數中必需包含timestamp參數31Invalid Timestamp非法的時間戳參數時間戳，格式為yyyy-mm-dd hh:mm:ss，例如：2008-01-25 20:23:30 。淘寶API服務端允許客戶端請求時間誤差為10分鐘32Missing Version缺少版本參數傳入的參數中必需包含v字段33Invalid Version非法的版本參數用戶傳入的版本號格式錯誤，必需為數字格式34Unsupported Version不支援的版本號使用者傳入的版本號碼沒有被提供42Insufficient session permissions短授權權限不足調用的是高危險API，請參考安全等級文件//open.taobao.com/doc/detail.htm?id=100243Parameter Error參數錯誤一般是用戶傳入參數非法造成的，請仔細檢查入參格式、範圍是否一一對應44Invalid access token無效的access token一般是用戶使用top協議獲取的sessionkey當做access token通過https方式調用API或調用環境搞錯47Invalid encoding編碼錯誤一般是使用者做http請求的時候沒有用UTF-8編碼請求造成的 |
平台級子錯誤
2、ISV業務錯誤
1.ISV業務級錯誤是ISV傳入的參數缺失，有誤或格式錯誤等原因造成的錯誤。因此isv應該根據錯誤訊息檢定是否傳入了對應的訊息，對於這一類錯誤建議改正後再重試。
主要包含兩個類別：
（1）錯誤碼為40,41的錯誤；40主要是必填參數沒有傳入報錯，41主要是傳入的參數格式不對報錯。 :2.
（2）錯誤碼大於100或等於15且子錯誤碼（sub_code）是"isv."開頭【( 錯誤碼> 100 或 錯誤碼= 15 ) and (isv開頭)】的呼叫錯誤:
2.錯誤回應是使用者和伺服器互動失敗的最直接展示，isv在呼叫top服務時，如果呼叫失敗，請盡量保留下錯誤日誌以便進行後面的錯誤追查。
#3、40/41錯誤介紹
| 錯誤碼錯誤描述-英文錯誤描述-中文解決方案40Missing Required Arguments缺少必選參數API文檔中設定為必選的參數是必傳的，請仔細核對文檔41Invalid Arguments非法的參數參數類型不對，例如：需要傳入的是數字類型的，卻傳入了字元類型的參數 |
4.業務層級子錯誤
| 子錯誤碼格式錯誤訊息歸屬者是否可在程式中重試isv. | -not-exist:* **根據***查詢不到
3、安全等級與安全漏洞錯誤碼
父錯誤碼訊息
#錯誤碼 | 英文描述 | 中文描述 | |
53 | Insufficient security level #### | 安全等級不足 | #提高應用程式安全等級或重新整理授權安全等級 |
子錯誤碼訊息
#
#子錯誤碼訊息 | 中文描述 | 歸屬方############################################################################## #######################high-risk security breach###################### ##存在高風險安全漏洞########################ISV########## | 解決安全漏洞後重新發布 |
mid-risk security breach | #存在中階安全漏洞 | ISV | #解決安全漏洞後重新發布 |
R1 security authorize missing | ##未進行R1層級授權 | ||
R1 security authorize invalid | ##R1等級授權過期 | #ISV | ##ISV |
| 進行R1等級授權（使用者重新授權或重新授權） | #R2 security authorize missing ###################未進行R2層級授權######### | ISV | #進行R2級授權（使用者重新授權或刷新授權） |
R2 security authorize invalid | R2層級授權過期 | #ISV | ##進行R2層級授權（使用者重新授權或刷新授權） |
W1 security authorize missing | #未進行W1等級授權 | ISV | #進行W1等級授權（使用者重新授權或刷新授權） |
W1 security authorize invalid | W1層級授權過期 | #ISV | #ISV |
##進行W1層級授權（使用者重新授權或刷新授權） | W2 security authorize invalid ###################未進行W2等級授權######### | ISV | #進行W2層級授權（使用者重新授權或刷新授權） |
W2 security authorize invalid | W2層級授權過期 | #ISV | ##進行W2層級授權（使用者重新授權或刷新授權） |
4、其它特有錯誤碼
#
