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