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