開(kāi)放平臺(tái)錯(cuò)誤自查手冊(cè)具體錯(cuò)誤墨靈

1、淘寶網(wǎng)開(kāi)放平臺(tái)錯(cuò)誤自查手冊(cè)本文檔針對(duì)2.0服務(wù)，文檔中的2.0的說(shuō)法是相對(duì)已下線的1.0而言的墨靈2010-10-15目錄一、錯(cuò)誤處理流程概覽3二、服務(wù)器響應(yīng)內(nèi)容透析41.調(diào)用成功返回格式42.調(diào)用錯(cuò)誤返回41)http連接錯(cuò)誤42)服務(wù)端錯(cuò)誤總述43)平臺(tái)解析錯(cuò)誤54)業(yè)務(wù)處理錯(cuò)誤6三、響應(yīng)格式錯(cuò)誤處理91.響應(yīng)格式格式錯(cuò)誤，但數(shù)據(jù)正確92.響應(yīng)格式錯(cuò)誤，數(shù)據(jù)也錯(cuò)誤10四、平臺(tái)級(jí)錯(cuò)誤處理11五、業(yè)務(wù)級(jí)錯(cuò)誤處理131.參數(shù)錯(cuò)誤132.權(quán)限控制133.用戶不存在134.服務(wù)錯(cuò)誤15a)服務(wù)調(diào)用錯(cuò)誤15b)服務(wù)調(diào)用異常15c)遠(yuǎn)程調(diào)用錯(cuò)誤15d)Top解析錯(cuò)誤15六、返回參數(shù)缺失處理161.整個(gè)消

2、息體為空或缺少文檔中說(shuō)明的結(jié)構(gòu)體返回。162.缺少fields指定字段返回16七、總結(jié)17一、 錯(cuò)誤處理流程概覽圖表 1 錯(cuò)誤處理流程從這個(gè)錯(cuò)誤處理流程可知，在整個(gè)錯(cuò)誤處理的過(guò)程中，一共可以分為3條主要的流程：請(qǐng)求解析異常流程處理，平臺(tái)級(jí)錯(cuò)誤處理和業(yè)務(wù)調(diào)用錯(cuò)誤處理。當(dāng)然，這一切處理的最初也是最重要的一步就是：將服務(wù)器響應(yīng)內(nèi)容保留下來(lái)。二、 服務(wù)器響應(yīng)內(nèi)容透析服務(wù)器響應(yīng)內(nèi)容，顧名思義就是isv調(diào)用top服務(wù)得到的響應(yīng)的內(nèi)容。這些內(nèi)容能夠最真實(shí)的反應(yīng)出isv請(qǐng)求的問(wèn)題和服務(wù)器當(dāng)前的情況，也最能夠幫助isv找到問(wèn)題的所在。服務(wù)器響應(yīng)內(nèi)容一般分為兩種：一種是wiki文檔中所編寫(xiě)的成功調(diào)用所返回的字段，

3、另一種是調(diào)用失敗的返回的錯(cuò)誤相關(guān)信息。1. 調(diào)用成功返回格式2.0的服務(wù)調(diào)用成功的響應(yīng)返回信息相對(duì)的規(guī)范化了。2.0的響應(yīng)內(nèi)容主要也可以分為3層：最外一層是你調(diào)用服務(wù)的名稱所對(duì)應(yīng)的響應(yīng)標(biāo)記，如：獲取單個(gè)商品（taobao.item.get）的響應(yīng)最外層為"item_get_response": ，表示這是獲取單個(gè)商品的響應(yīng)；中間一層是返回結(jié)構(gòu)體的標(biāo)記。如果結(jié)構(gòu)體是單個(gè)，那么2.0返回的這一層里面就會(huì)是單個(gè)的結(jié)構(gòu)，如：獲取的單個(gè)商品的結(jié)構(gòu)體就是"item": ；反之，如果結(jié)構(gòu)體是多個(gè)，那么列表也會(huì)明顯的表示出來(lái)，如：搜索商品列表的結(jié)構(gòu)體就會(huì)是”items”

4、:“item”: , 。最外層的items表示這是一個(gè)商品的列表，后面的item表示列表中的每一個(gè)子結(jié)構(gòu)體都是屬于商品item的，然后就跟著商品的數(shù)據(jù)；最內(nèi)一層就商品的具體字段信息了。2. 調(diào)用錯(cuò)誤返回當(dāng)調(diào)用發(fā)生錯(cuò)誤的時(shí)候，一般情況下可以分為幾大類錯(cuò)誤信息的返回：http連接錯(cuò)誤、平臺(tái)解析錯(cuò)誤、業(yè)務(wù)處理錯(cuò)誤。這三種類型的錯(cuò)誤分別代表了：淘寶服務(wù)器、淘寶接入平臺(tái)、top-api業(yè)務(wù)，幾個(gè)層次上出現(xiàn)的問(wèn)題。1) http連接錯(cuò)誤http連接錯(cuò)誤是請(qǐng)求通信過(guò)程中出現(xiàn)的錯(cuò)誤，這類型錯(cuò)誤通常由http響應(yīng)碼標(biāo)記出來(lái)。http響應(yīng)碼由三位十進(jìn)制數(shù)字組成，它們出現(xiàn)在由HTTP服務(wù)器發(fā)送的響應(yīng)的第一行。響應(yīng)碼

5、分五種類型，由它們的第一位數(shù)字表示：1xx：信息，請(qǐng)求收到，繼續(xù)處理2xx：成功，行為被成功地接受、理解和采納3xx：重定向，為了完成請(qǐng)求，必須進(jìn)一步執(zhí)行的動(dòng)作4xx：客戶端錯(cuò)誤，請(qǐng)求包含語(yǔ)法錯(cuò)誤或者請(qǐng)求無(wú)法實(shí)現(xiàn)5xx：服務(wù)器錯(cuò)誤，服務(wù)器不能實(shí)現(xiàn)一種明顯無(wú)效的請(qǐng)求Isv調(diào)用top服務(wù)最常收到就是200：http請(qǐng)求成功；404：未找到請(qǐng)求的服務(wù)；500內(nèi)部服務(wù)器錯(cuò)誤等等。如果用戶收到的響應(yīng)碼是404，表示用戶的網(wǎng)絡(luò)有問(wèn)題或者top被和諧了如果用戶收到的響應(yīng)碼是500，表示網(wǎng)絡(luò)是ok的，是top的服務(wù)無(wú)法響應(yīng)。2) 服務(wù)端錯(cuò)誤總述平臺(tái)解析錯(cuò)誤和業(yè)務(wù)處理錯(cuò)誤都是http成功訪問(wèn)到top服務(wù)（htt

6、p響應(yīng)碼返回為200）之后所產(chǎn)生的錯(cuò)信息，他們top處理isv請(qǐng)求過(guò)程中出現(xiàn)的問(wèn)題。2.0的錯(cuò)誤響應(yīng)信息的最外層為“error_response”:” ”，表示這是調(diào)用服務(wù)失敗所返回的錯(cuò)誤信息。信息體里面一層總共包含了五個(gè)元素："args":"arg":“key”:“ ”,”value”:” ”,“key”:“ ”,”value”:” ”,“key”:“ ”,”value”:” ”，”code”:” ”， “msg”:” ”，”sub_code”:” ”和”sub_msg”:” ”。args表示用戶傳入的參數(shù)列表是什么，里面是一個(gè)arg的列表會(huì)包含用戶傳

7、入的所有參數(shù)信息，每個(gè)arg表示一個(gè)參數(shù)的信息，key表示參數(shù)的名稱，value表示參數(shù)的內(nèi)容，用以方便用戶定位自己的錯(cuò)誤；code表示用戶調(diào)用錯(cuò)誤的錯(cuò)誤碼是多少，小于200表示平臺(tái)級(jí)錯(cuò)誤，200-1000之間表示大范圍的業(yè)務(wù)錯(cuò)誤，即哪一類型的api調(diào)用發(fā)生了錯(cuò)誤（根據(jù)api的大類來(lái)分，如：商品類的api是530，交易類的api是520，等）；msg表示大類型的錯(cuò)誤碼所對(duì)應(yīng)的錯(cuò)誤信息，一般不具備獨(dú)立的debug作用，需要和sub_code和sub_msg一起使用才行；sub_code是調(diào)用錯(cuò)誤的子錯(cuò)誤碼，他表示用戶調(diào)用錯(cuò)誤的原因；sub_msg是子錯(cuò)誤碼所對(duì)應(yīng)的錯(cuò)誤信息，他用來(lái)補(bǔ)充細(xì)化子錯(cuò)誤碼

8、的錯(cuò)誤原因的。例如調(diào)用2.0的taobao.item.get服務(wù)錯(cuò)誤時(shí)返回的錯(cuò)誤信息："error_response":"args":"arg":"key":"app_key","value":"15739","key":"fields","value":"list_time,delist_time,approve_status","key":"f

9、ormat","value":"json","key":"method","value":"taobao.item.get","key":"nick","value":"tbtest561","key":"partner_id","value":"TOPTEST","key":"

10、sign","value":"668FB4A049F71A1C845EF8C05B1F3E66","key":"timestamp","value":"2010-03-05 18:03:06.325","key":"v","value":"2.0","code":530,"msg":"Remote service error",

11、"sub_code":"missing-parameter","sub_msg":"iid和num_iid至少要傳入一個(gè)"這個(gè)信息的開(kāi)頭為error_response，表示這是調(diào)用錯(cuò)誤所返回的錯(cuò)誤信息。里面的args列出了用調(diào)用這個(gè)接口傳入的信息有："key":"app_key","value":"15739","key":"fields","value":"list

12、_time,delist_time,approve_status","key":"format","value":"json","key":"method","value":"taobao.item.get","key":"nick","value":"tbtest561","key":"partner_id"

13、;,"value":"TOPTEST","key":"sign","value":"668FB4A049F71A1C845EF8C05B1F3E66","key":"timestamp","value":"2010-03-05 18:03:06.325","key":"v","value":"2.0"這些信息是從用戶的

14、請(qǐng)求信息里面解析出來(lái)的。錯(cuò)誤碼code為530，表示這是調(diào)用商品的api所產(chǎn)生的錯(cuò)誤。錯(cuò)誤信息msg為Remote service error表示這是調(diào)用業(yè)務(wù)處理所產(chǎn)生的錯(cuò)誤。子錯(cuò)誤碼sub_code為：missing-parameter，表示這個(gè)錯(cuò)誤是因?yàn)槿鄙倭藚?shù)所產(chǎn)生的。子錯(cuò)誤信息sub_msg為：iid和num_iid至少要傳入一個(gè)，表示少傳的參數(shù)為iid或num_iid。這所有的錯(cuò)誤信息疊加起來(lái)可以知道，這個(gè)錯(cuò)誤是用戶調(diào)用taobao.item.get接口時(shí)業(yè)務(wù)處理發(fā)現(xiàn)用戶沒(méi)有傳入商品id所導(dǎo)致的。3) 平臺(tái)解析錯(cuò)誤平臺(tái)解析錯(cuò)誤是指top返回的錯(cuò)誤碼小于100的情況。平臺(tái)解析是非業(yè)務(wù)

15、性的普適的校驗(yàn)接入層，主要用于對(duì)用戶的各種權(quán)限、和入?yún)⑦M(jìn)行最基本的校驗(yàn)?，F(xiàn)在的平臺(tái)錯(cuò)誤碼主要有：錯(cuò)誤碼 錯(cuò)誤描述（英文） 錯(cuò)誤描述（中文） 錯(cuò)誤來(lái)源3Upload Fail 圖片上傳失敗 平臺(tái)本身4User Call Limited 用戶調(diào)用次數(shù)超限 ISV5Session Call Limited 會(huì)話調(diào)用次數(shù)超限 ISV6Partner Call Limited 合作伙伴調(diào)用次數(shù)超限 ISV7App Call Limited 應(yīng)用調(diào)用次數(shù)超限 ISV8App Call Exceeds Limited Frequency 應(yīng)用調(diào)用頻率超限 ISV9Http Action Not Allowe

16、d HTTP方法被禁止（請(qǐng)用大寫(xiě)的POST或GET） ISV10Service Currently Unavailable 服務(wù)不可用 平臺(tái)本身11Insufficient ISV Permissions 開(kāi)發(fā)者權(quán)限不足 ISV12Insufficient User Permissions 用戶權(quán)限不足 ISV13Insufficient Partner Permissions 合作伙伴權(quán)限不足 ISV15Remote Service Error 遠(yuǎn)程服務(wù)出錯(cuò) 平臺(tái)本身21Missing Method 缺少方法名參數(shù) 平臺(tái)本身22Invalid Method 不存在的方法名 ISV23Inva

17、lid Format 非法數(shù)據(jù)格式 ISV24Missing Signature 缺少簽名參數(shù) ISV25Invalid Signature 非法簽名 ISV26Missing Session 缺少SessionKey參數(shù) 平臺(tái)本身27Invalid Session 非法的SessionKey參數(shù) ISV28Missing App Key 缺少AppKey參數(shù) 平臺(tái)本身29Invalid App Key 非法的AppKey參數(shù) ISV30Missing Timestamp 缺少時(shí)間戳參數(shù) 平臺(tái)本身31Invalid Timestamp 非法的時(shí)間戳參數(shù) ISV32Missing Version

18、 缺少版本參數(shù) 平臺(tái)本身33Invalid Version 非法的版本參數(shù) ISV34Unsupported Version 不支持的版本號(hào) ISV40Missing Required Arguments 缺少必選參數(shù) 平臺(tái)本身41Invalid Arguments 非法的參數(shù) ISV42Forbidden Request 請(qǐng)求被禁止 ISV43Parameter Error 參數(shù)錯(cuò)誤 ISV 圖表 2 平臺(tái)錯(cuò)誤碼列表Isv可以通過(guò)錯(cuò)誤碼和解釋來(lái)糾正問(wèn)題。如：錯(cuò)誤碼為3的響應(yīng)表示圖片上傳失敗，錯(cuò)誤碼為26表示用戶沒(méi)有傳入session參數(shù)，錯(cuò)誤碼為27表示用戶傳入的session參數(shù)找不到對(duì)應(yīng)

19、的session記錄，等等。4) 業(yè)務(wù)處理錯(cuò)誤業(yè)務(wù)處理錯(cuò)誤是用戶通過(guò)平臺(tái)校驗(yàn)進(jìn)入業(yè)務(wù)流程出現(xiàn)了錯(cuò)誤所發(fā)出來(lái)的2.0調(diào)用失敗后服務(wù)器所返回的錯(cuò)誤信息格式就是：“error_response”:"args":"arg":“key”:“ ”,”value”:” ”,“key”:“ ”,”value”:” ”,“key”:“ ”,”value”:” ”,”code”:” ”,“msg”:” ”,”sub_code”:” ”,”sub_msg”:” ”，里面的code是數(shù)字形式的標(biāo)記著一種業(yè)務(wù)類型的錯(cuò)誤編碼，msg則是比較大范圍內(nèi)的表示錯(cuò)誤類型的字符串。而sub_

20、code是以字符串形式粗略表示錯(cuò)誤的類型，sub_msg則是表示具體的錯(cuò)誤原因。2.0的code包含以下幾種分類：產(chǎn)品線錯(cuò)誤碼用戶500類目510交易520退款521商品530商品擴(kuò)展API531郵費(fèi)模板532產(chǎn)品540物流550店鋪560評(píng)價(jià)570淘寶客580系統(tǒng)590備案591增量API600比價(jià)610畫(huà)報(bào)620江湖630分銷640淘秀650收費(fèi)660Misc(保證金等雜項(xiàng)api)670圖表 3 業(yè)務(wù)處理錯(cuò)誤碼分類列表由上圖可知，每一大類的api在2.0中其實(shí)是共享一個(gè)code的，它能讓用戶在復(fù)雜組合調(diào)用中指導(dǎo)是哪一類的api出現(xiàn)了問(wèn)題，實(shí)現(xiàn)初步的定位。2.0的業(yè)務(wù)錯(cuò)誤中，msg里面最容易

21、出現(xiàn)的內(nèi)容就是Remote service error，這表示用戶是在通過(guò)了平臺(tái)校驗(yàn)后進(jìn)行業(yè)務(wù)流程的時(shí)候出現(xiàn)的錯(cuò)誤。其他的錯(cuò)誤還有Remote Service Timeout：后臺(tái)處理業(yè)務(wù)超時(shí)等等的錯(cuò)誤。這一個(gè)錯(cuò)誤信息的力度比較粗，很難單獨(dú)用地進(jìn)行錯(cuò)誤處理。2.0的業(yè)務(wù)處理錯(cuò)誤信息主要要看sub_code和sub_msg這兩個(gè)字段。sub_code表示了服務(wù)對(duì)業(yè)務(wù)錯(cuò)誤的分類，sub_msg表示了是錯(cuò)誤原因。sub_code根據(jù)業(yè)務(wù)錯(cuò)誤類型主要可以分為如下幾類：子錯(cuò)誤碼格式錯(cuò)誤信息isv.#-not-exist:*根據(jù)*查詢不到#isv.missing-parameter:*缺少必要的參數(shù)*is

22、v.invalid-paramete:*參數(shù)*無(wú)效，格式不對(duì)、非法值、越界等isv.invalid-permission權(quán)限不夠、非法訪問(wèn)isv.parameters-mismatch:*-and-#傳入的參數(shù)*和#不匹配，兩者有一定的對(duì)應(yīng)關(guān)系isv.*-service-error:#調(diào)用*服務(wù)返回false，業(yè)務(wù)邏輯錯(cuò)誤，#表示具體的錯(cuò)誤信息isp.*-service-unavailable調(diào)用后端服務(wù)*拋異常，服務(wù)不可用isp.remote-service-error連接遠(yuǎn)程服務(wù)錯(cuò)誤isp.remote-service-timeout連接遠(yuǎn)程服務(wù)超時(shí)isp.remote-connectio

23、n-error遠(yuǎn)程連接錯(cuò)誤isp.null-pointer-exception空指針異常錯(cuò)誤isp.top-parse-errorapi解析錯(cuò)誤（出現(xiàn)了未被明確控制的異常信息）isp.top-remote-connection-timeouttop平臺(tái)連接后端服務(wù)超時(shí)isp.top-remote-connection-errortop平臺(tái)連接后端服務(wù)錯(cuò)誤，找不到服務(wù)isp.top-mapping-parse-errortop-mapping轉(zhuǎn)換出錯(cuò)，主要是由于傳入?yún)?shù)格式不對(duì)，top需要加強(qiáng)判斷isp.unknown-errortop平臺(tái)連接后端服務(wù)拋未知異常信息圖表 4 子錯(cuò)誤碼列表從上面的

24、錯(cuò)誤列表中可以看出，以isv開(kāi)頭的一般都是isv的錯(cuò)誤，這一類錯(cuò)誤一般是由于用戶提供的參數(shù)不合法或者不匹配造成的，因此isv應(yīng)該根據(jù)錯(cuò)誤信息檢驗(yàn)是否傳入了相應(yīng)的信息，對(duì)于這一類錯(cuò)誤建議改正后再重試；以isp開(kāi)頭的錯(cuò)誤一般是isp服務(wù)不可用或top平臺(tái)連接后端服務(wù)時(shí)的錯(cuò)誤，這些錯(cuò)誤可能與后臺(tái)服務(wù)端的服務(wù)可用性有關(guān)，建議用戶在一段時(shí)間后重試。錯(cuò)誤響應(yīng)時(shí)用戶和服務(wù)器交互失敗的最直接展示，isv在調(diào)用top服務(wù)時(shí)，如果調(diào)用失敗，請(qǐng)盡量保留下錯(cuò)誤信息以便進(jìn)行后面的錯(cuò)誤追查。三、 響應(yīng)格式錯(cuò)誤處理響應(yīng)格式錯(cuò)誤是指用戶調(diào)用top服務(wù)時(shí)，傳入?yún)?shù)設(shè)置了format參數(shù)為json，但是接受到的卻為xml的響應(yīng)格

25、式，或者設(shè)置格式為xml接收到的卻為json響應(yīng)的格式的情況。一般正常情況下這種情況是不會(huì)出現(xiàn)的，但是還是會(huì)有一些異常的情況會(huì)引起這個(gè)問(wèn)題。這種響應(yīng)格式錯(cuò)誤的問(wèn)題在isv的程序中通常會(huì)表現(xiàn)為，響應(yīng)解析格式錯(cuò)誤。例如：用戶使用的top的java SDK客戶端調(diào)用top服務(wù)，設(shè)置的format格式為json卻得到了一個(gè)xml的響應(yīng)，這是sdk就會(huì)報(bào)一個(gè)錯(cuò)誤說(shuō)響應(yīng)開(kāi)始處缺少一個(gè)“”符號(hào)。這是因?yàn)閤ml響應(yīng)是以“<”開(kāi)始的緣故。一般會(huì)發(fā)生這種現(xiàn)象的原因有一下三種：用戶傳入的參數(shù)過(guò)大導(dǎo)致流解析異常，用戶調(diào)用太過(guò)頻繁導(dǎo)致的響應(yīng)異常，top服務(wù)器故障。為了定位到問(wèn)題出在哪里，以便找到相應(yīng)的解決方法，用

26、戶在遇到響應(yīng)格式錯(cuò)誤的情況時(shí)可以參考以下步驟進(jìn)行調(diào)試。圖表 5 響應(yīng)格式錯(cuò)誤處理流程1. 響應(yīng)格式格式錯(cuò)誤，但數(shù)據(jù)正確用戶第一步應(yīng)該分析一下相應(yīng)的內(nèi)容里面是不是除了格式錯(cuò)誤以外，其他的響應(yīng)內(nèi)容都是正確調(diào)用的返回結(jié)果。例如，有個(gè)用戶用top的sdk，設(shè)置format為json，調(diào)用top得到了這樣一個(gè)返回結(jié)果：com.taobao.api.json.JSONException: A JSONObject text must begin with '' at character 1&

27、#160;<?xml version="1.0" encoding="utf-8" ?><rsp><totalResults>1115</totalResults><item><iid><!CDATA77a003aef35f8d959eef03d7ba3d23e3></iid><modified>2010-03-01 16:04:15</modified></item><item

28、><iid><!CDATAc559afab73ab721a8e7500b62864add0></iid><modified>2010-03-01 16:04:05</modified></item><item><iid><!CDATA28a3410c88bc2ba2471080ce8891eaf7></iid><modified>2010-03-01 16:03:59</modified></item><it

29、em><iid><!CDATA915383f4733b7a7c2549aa863d305995></iid><modified>2010-03-01 16:03:53</modified></item><item><iid><!CDATA528223dc2d67213aa29ab84c74c6a60a></iid><modified>2010-03-01 07:30:52</modified></item><

30、/rsp>從這個(gè)異常的開(kāi)頭可以看到，這是sdk的json解析拋了一個(gè)異常，說(shuō)響應(yīng)內(nèi)容的內(nèi)容應(yīng)該是以“”開(kāi)始的。這說(shuō)名，isv收到的響應(yīng)格式肯定出了問(wèn)題。再看一下響應(yīng)的內(nèi)容<rsp></rsp>相應(yīng)結(jié)果標(biāo)簽之間包含了totalResults和item列表，這些數(shù)據(jù)表明，這是調(diào)用商品查詢接口返回的結(jié)果數(shù)據(jù)：查詢到的結(jié)果總數(shù)是1115條，當(dāng)前頁(yè)的商品iid和最近修改時(shí)間也在其中。這些查詢結(jié)果數(shù)據(jù)是正常的，但是返回格式卻不是傳入的json而是變成了xml。這位isv聯(lián)系了top的技術(shù)支持，在建議減緩調(diào)用頻率以后，返回的數(shù)據(jù)格式正常了，這樣就臨時(shí)控制了這種情況的發(fā)生。同時(shí)技

31、術(shù)支持將這些情況反映到了開(kāi)發(fā)，top這邊后續(xù)就會(huì)找到問(wèn)題根源，進(jìn)一步杜絕這種情況的發(fā)生。2. 響應(yīng)格式錯(cuò)誤，數(shù)據(jù)也錯(cuò)誤如果用戶第一步分析發(fā)現(xiàn)，返回的信息并不是調(diào)用成功的信息而是某個(gè)平臺(tái)錯(cuò)誤，而且用戶本身的參數(shù)并不會(huì)導(dǎo)致這個(gè)錯(cuò)誤的產(chǎn)生，此時(shí)用戶就需要查看自己調(diào)用接口的參數(shù)了。如果用戶調(diào)用的接口需要傳入比較大的數(shù)據(jù)（如：圖片、商品的長(zhǎng)篇描述等等），那么用戶應(yīng)首先嘗試著減小這些入?yún)⒌胶戏ǚ秶鷥?nèi)輸入（傳入小圖片或者只傳入少量的描述文字等）。如果用戶調(diào)用成功，表示錯(cuò)誤是因?yàn)橛脩羧雲(yún)⑻笤斐闪私馕鲥e(cuò)誤引起的，用戶應(yīng)配合自己所在地方的網(wǎng)速，請(qǐng)求大小等等的信息合理設(shè)置自己的參數(shù)大小和接口調(diào)用順序。如果用戶減小

32、參數(shù)還是解析失敗的話，用戶嘗試著不傳入圖片或只傳入幾個(gè)字節(jié)的描述的內(nèi)容進(jìn)行接口調(diào)用。在傳入描述只有很少的字節(jié)的情況下：如果不傳圖片調(diào)用成功了，那么應(yīng)該是top的服務(wù)器的問(wèn)題，請(qǐng)將這個(gè)情況反饋給技術(shù)支持進(jìn)行解決；如果圖片不傳調(diào)用仍然失敗了，那么應(yīng)該是用戶的調(diào)用參數(shù)或網(wǎng)絡(luò)有問(wèn)題，請(qǐng)仔細(xì)對(duì)照文檔說(shuō)明對(duì)參數(shù)進(jìn)行修改或等待網(wǎng)絡(luò)狀態(tài)好一點(diǎn)的時(shí)候進(jìn)行調(diào)用。總的來(lái)說(shuō)，如果用戶發(fā)生了響應(yīng)格式錯(cuò)誤的情況，一般分為三種情況：用戶本身傳入的format就是錯(cuò)誤的，這種情況用戶需要查看自己傳入的參數(shù)是否正確；用戶通信的網(wǎng)絡(luò)太差，服務(wù)端造成請(qǐng)求解析失敗而丟失了format信息，這種情況下用戶需要調(diào)整自己的網(wǎng)絡(luò)通信情況，等

33、狀況恢復(fù)再調(diào)用；如果是其他由于圖片或調(diào)用太頻繁而引起的問(wèn)題，用戶需要減小圖片或減緩調(diào)用來(lái)提高成功率，并且將這些情況通報(bào)給top技術(shù)支持的同學(xué)。四、 平臺(tái)級(jí)錯(cuò)誤處理在前文的錯(cuò)誤綜述中介紹過(guò)，top的錯(cuò)誤可以分為平臺(tái)級(jí)錯(cuò)誤和業(yè)務(wù)級(jí)錯(cuò)誤。所謂平臺(tái)級(jí)錯(cuò)誤就是指：錯(cuò)誤碼小于100的調(diào)用錯(cuò)誤。這種錯(cuò)誤一般是由于用戶的請(qǐng)求不符合各種的基本校驗(yàn)而引起的。下面將對(duì)于各種平臺(tái)級(jí)錯(cuò)誤及相應(yīng)的解決辦法陳列于此。錯(cuò)誤碼錯(cuò)誤解釋解決辦法3圖片上傳失敗將傳入的圖片格式改為正確的格式、適當(dāng)?shù)拇笮〉膱D片放進(jìn)消息體里面?zhèn)鬏斶^(guò)來(lái)。如果傳輸仍然失敗需要減小圖片大小或者增加網(wǎng)絡(luò)帶寬進(jìn)行嘗試4用戶調(diào)用次數(shù)超限調(diào)整程序邏輯合理利用api，

34、等第二天再調(diào)用?；蛘呦蚣夹g(shù)運(yùn)維的同學(xué)申請(qǐng)?jiān)黾诱{(diào)用次數(shù)5會(huì)話調(diào)用次數(shù)超限6合作伙伴調(diào)用次數(shù)超限7應(yīng)用調(diào)用次數(shù)超限8應(yīng)用調(diào)用頻率超限Isv調(diào)節(jié)api調(diào)用頻率，不能太過(guò)頻繁的調(diào)用9HTTP方法被禁止請(qǐng)用大寫(xiě)的POST或GET，如果有圖片等信息傳入則一定要用POST才可以10服務(wù)不可用多數(shù)是由未知異常引起的，用戶仔細(xì)檢查自己傳入的參數(shù)是否符合文檔中描述的樣子11開(kāi)發(fā)者權(quán)限不足appKey所對(duì)應(yīng)的應(yīng)用不具備權(quán)限調(diào)用當(dāng)前接口。需要聯(lián)系運(yùn)營(yíng)或技術(shù)支持的同學(xué)開(kāi)通調(diào)用該接口的權(quán)限。12用戶權(quán)限不足13合作伙伴權(quán)限不足15遠(yuǎn)程服務(wù)出錯(cuò)Api調(diào)用后端服務(wù)出錯(cuò)，isv首先查看自己的參數(shù)是否合法，如果參數(shù)沒(méi)有問(wèn)題請(qǐng)過(guò)一

35、段時(shí)間再嘗試，如果還不行請(qǐng)聯(lián)系技術(shù)支持21缺少方法名參數(shù)傳入的參數(shù)加入method字段22不存在的方法名傳入的method字段必需是你所調(diào)用的api的名稱，并且該api是確實(shí)存在的23非法數(shù)據(jù)格式傳入的format必需為json或xml中的一種24缺少簽名參數(shù)傳入的參數(shù)中必需包含sign字段25非法簽名簽名必需根據(jù)正確的算法算出來(lái)的。算法請(qǐng)見(jiàn)：簽名算法26缺少SessionKey參數(shù)傳入的參數(shù)中必需包含session字段27非法的SessionKey參數(shù)傳入的session必需是用戶綁定session拿到的。如果報(bào)session不合法可能是用戶沒(méi)有綁定session或session過(guò)期造成的，

36、用戶需要重新綁定一下然后傳入新的sessionKey。28缺少AppKey參數(shù)傳入的參數(shù)必需包含app_key字段29非法的AppKey參數(shù)用戶傳入的appKey參數(shù)確實(shí)是要存在的，如果沒(méi)有申請(qǐng)appKey的同學(xué)請(qǐng)去申請(qǐng)appKey，如果是已經(jīng)有了appKey卻調(diào)用不同過(guò)的，請(qǐng)聯(lián)系技術(shù)支持解決30缺少時(shí)間戳參數(shù)傳入的參數(shù)中必需包含timestamp參數(shù)31非法的時(shí)間戳參數(shù)用戶傳入的時(shí)間戳不合法。時(shí)間戳，格式為yyyy-mm-dd hh:mm:ss，例如：2008-01-25 20:23:30。淘寶API服務(wù)端允許客戶端請(qǐng)求時(shí)間誤差為10分鐘。32缺少版本參數(shù)傳入的參數(shù)中必需包含v字段33非法的

37、版本參數(shù)用戶傳入的版本號(hào)格式錯(cuò)誤，必需為數(shù)字格式34不支持的版本號(hào)用戶傳入的版本號(hào)沒(méi)有被提供?，F(xiàn)在top只支持2.0的版本，1.0版本已經(jīng)下線。40缺少必選參數(shù)用戶傳入的參數(shù)中漏掉了必傳的參數(shù)。請(qǐng)仔細(xì)對(duì)照文檔檢查41非法的參數(shù)用戶傳入的參數(shù)不符合文檔中說(shuō)明的參數(shù)格式，請(qǐng)參照文檔進(jìn)行修改42請(qǐng)求被禁止請(qǐng)求 被禁止（目前沒(méi)有在控制）43參數(shù)錯(cuò)誤參數(shù)解析發(fā)生錯(cuò)誤或異常。一般是用戶傳入?yún)?shù)非法引起的。請(qǐng)仔細(xì)檢查入?yún)⒏袷?、范圍、是否一一?duì)應(yīng)等等情況。44Isp error后臺(tái)接入服務(wù)錯(cuò)誤這種后臺(tái)服務(wù)異常引起的錯(cuò)誤，請(qǐng)聯(lián)系技術(shù)支持。45非法的版本號(hào)，API1.0已經(jīng)關(guān)閉，建議使用2.0圖表 6 平臺(tái)級(jí)錯(cuò)誤

38、碼及其解決方案基本上來(lái)說(shuō)，平臺(tái)錯(cuò)誤是一個(gè)通用的、普適的校驗(yàn)。一般針對(duì)用戶的權(quán)限、安全、流量和最基本的參數(shù)等等進(jìn)行校驗(yàn)。用戶遇到這些錯(cuò)誤的返回一定要第一步檢查自己的權(quán)限、頻率等情況；然后就需要參照文檔檢驗(yàn)一下自己的傳入的參數(shù)是否完整且合法；如果這些都無(wú)法解決問(wèn)題，請(qǐng)聯(lián)系技術(shù)支持的同學(xué)進(jìn)行反饋，top后臺(tái)會(huì)盡快解決這些問(wèn)題。五、 業(yè)務(wù)級(jí)錯(cuò)誤處理業(yè)務(wù)級(jí)錯(cuò)誤是指isv請(qǐng)求進(jìn)入top業(yè)務(wù)處理以后爆出來(lái)的業(yè)務(wù)相關(guān)的錯(cuò)誤。Top的業(yè)務(wù)錯(cuò)誤一般可以分為4個(gè)大類：參數(shù)錯(cuò)誤、權(quán)限控制、用戶不存在和服務(wù)錯(cuò)誤。詳細(xì)的分類可參見(jiàn)“圖表4子錯(cuò)誤碼列表”。1. 參數(shù)錯(cuò)誤參數(shù)錯(cuò)誤指topapi根據(jù)業(yè)務(wù)要求對(duì)用戶傳入的參數(shù)進(jìn)行

39、校驗(yàn)組裝的時(shí)候產(chǎn)生的錯(cuò)誤。2.0中的參數(shù)錯(cuò)誤的錯(cuò)誤碼是在調(diào)用返回的sub_code子錯(cuò)誤碼里面得到具體體現(xiàn)的。2.0的參數(shù)錯(cuò)誤一般有如下幾個(gè)錯(cuò)誤碼：missing-parameter，invalid-parameter，parameters-mismatch，XXX-not-exist等等。missing-parameter表示缺少了某些必傳參數(shù)（如：獲取單個(gè)商品是iid和num_iid一個(gè)都沒(méi)傳入）；invalid-parameter表示用戶傳入的參數(shù)錯(cuò)誤（如：傳入的iids個(gè)數(shù)不符合規(guī)定，傳入的iid對(duì)應(yīng)的商品已刪除等等）；parameters-mismatch表示用戶傳入的某些有對(duì)應(yīng)關(guān)系

40、的參數(shù)個(gè)數(shù)不匹配了（如：input_pids和input_str長(zhǎng)度不匹配，或者sku_properties和sku的其他參數(shù)個(gè)數(shù)不匹配）；XXX-not-exist表示用戶指定的參數(shù)找不到對(duì)應(yīng)的記錄（即這個(gè)參數(shù)所對(duì)應(yīng)的記錄不存在或已經(jīng)被刪除了）。這些參數(shù)錯(cuò)誤，都是由于isv傳入的參數(shù)有問(wèn)題而引起的。用戶在遇到報(bào)參數(shù)錯(cuò)誤的情況下，需要查看對(duì)應(yīng)的錯(cuò)誤消息內(nèi)容（2.0是sub_msg）中的說(shuō)明來(lái)進(jìn)行入?yún)⑿薷?。建議將這部分內(nèi)容展示給用戶，可以讓用直觀的看到錯(cuò)誤的原因，從而改進(jìn)輸入。2. 權(quán)限控制權(quán)限控制的錯(cuò)誤是指用戶使用了自己不享有的服務(wù)所造成的錯(cuò)誤。這類型的錯(cuò)誤： 2.0的子錯(cuò)誤碼為：invali

41、d-permission。這類型的錯(cuò)誤通常都是用戶進(jìn)行的操作觸碰到了淘寶的業(yè)務(wù)規(guī)則，導(dǎo)致了top的業(yè)務(wù)校驗(yàn)不通過(guò)。如：用戶沒(méi)有登錄卻要獲取某個(gè)賣家倉(cāng)庫(kù)中的商品，用戶不享有多圖服務(wù)卻要上傳商品多圖或商品屬性圖片，成人類目直接上傳圖片，修改自動(dòng)發(fā)貨的商品，不是賣家或買家卻要獲取交易詳細(xì)信息的這些錯(cuò)誤并不是用戶傳入的參數(shù)找不到相應(yīng)的數(shù)據(jù)、或者傳入的參數(shù)是錯(cuò)誤的造成的。相反的，用戶傳入的參數(shù)都符合文檔描述，但是用戶不具備權(quán)限來(lái)進(jìn)行相應(yīng)的操作。在這種情況下，isv有幾條路可以選擇：第一：對(duì)于查詢類型的權(quán)限控制：如果用戶是信息的所有者，那么需要讓用戶進(jìn)行登錄綁定，這樣用戶就夠進(jìn)行權(quán)限控制的操作了；如果用戶

42、不是信息的合法查看人，那么isv要明確的告訴用戶這個(gè)操作不可以進(jìn)行，并且不要進(jìn)行重試操作了。第二：對(duì)于增刪改類型的操作的權(quán)限控制：如果用戶是因?yàn)闆](méi)有享有服務(wù)（如：沒(méi)有享有圖片空間的服務(wù)）而產(chǎn)生的權(quán)限限制，isv需要引導(dǎo)用戶去進(jìn)行服務(wù)的開(kāi)通后再來(lái)進(jìn)行操作，之后再重新調(diào)用接口；如果是因?yàn)橛脩舨僮髁藙e人的數(shù)據(jù)而引起的權(quán)限控制，那么isv要明確的跟用戶報(bào)錯(cuò)，并且不能再進(jìn)行重試操作。總之，當(dāng)用戶遇到報(bào)權(quán)限控制的錯(cuò)誤時(shí)，isv不能直接進(jìn)行重試。應(yīng)該將問(wèn)題直接告訴用戶，并引導(dǎo)用戶進(jìn)行相關(guān)的登錄、開(kāi)通服務(wù)等操作來(lái)調(diào)整權(quán)限以后，再讓用戶重試操作。如果用戶不愿意進(jìn)行調(diào)整，isv此時(shí)應(yīng)該直接停止該操作，不能默認(rèn)的進(jìn)

43、行重試，因?yàn)檫@種前提下，重試是完全沒(méi)有作用的。3. 用戶不存在用戶不存在是指top后臺(tái)根據(jù)用戶綁定的nick或者傳入的nick對(duì)用戶信息進(jìn)行查詢的時(shí)候找不到用戶記錄所報(bào)出的錯(cuò)誤。2.0的子錯(cuò)誤碼：user-not-exist。用戶遇到這種問(wèn)題首先請(qǐng)確認(rèn)調(diào)用的這個(gè)接口自己有沒(méi)有傳入nick這個(gè)參數(shù)。如果nick是根據(jù)用戶綁定的session取得的，那么用戶需要過(guò)一會(huì)兒再重新調(diào)用看看。如果隔一段時(shí)間還不行，請(qǐng)聯(lián)系技術(shù)支持解決。如果用戶自己通過(guò)參數(shù)傳入了nick，那么請(qǐng)用戶仔細(xì)檢查自己傳入的nick是否正確。例如：有沒(méi)有多一個(gè)空格或者大小寫(xiě)錯(cuò)誤的？該用戶是否確實(shí)存在的？等等。如果問(wèn)題是因?yàn)槊Q錯(cuò)誤或

44、用戶確實(shí)不存在引起，用戶需要更改輸入?yún)?shù)后才能再次調(diào)用。如果用戶名稱正確，用戶也確實(shí)存在，卻還是報(bào)用戶不存在錯(cuò)誤，用戶需要檢查傳入的nick是否包含難以識(shí)別的編碼的字體。如果nick中包含了火星文或者其他編碼的字體，請(qǐng)考慮將nick轉(zhuǎn)換成utf8以后重新嘗試或者放棄此次操作。如果上述問(wèn)題都不存在，請(qǐng)聯(lián)系技術(shù)支持的同學(xué)進(jìn)行查看。用戶不存在的整個(gè)查錯(cuò)過(guò)程如下所示：圖表 7 user-not-exist錯(cuò)誤的查錯(cuò)流程4. 服務(wù)錯(cuò)誤服務(wù)錯(cuò)誤主要指用戶的請(qǐng)求通過(guò)了api業(yè)務(wù)的基本校驗(yàn)，在調(diào)用后臺(tái)服務(wù)的時(shí)候由于出現(xiàn)了異常或者更進(jìn)步的業(yè)務(wù)報(bào)錯(cuò)而產(chǎn)生的錯(cuò)誤。這一類錯(cuò)誤主要分為4個(gè)大類：服務(wù)調(diào)用錯(cuò)誤、服務(wù)調(diào)用異

45、常、遠(yuǎn)程調(diào)用錯(cuò)誤、top解析錯(cuò)誤。a) 服務(wù)調(diào)用錯(cuò)誤服務(wù)調(diào)用錯(cuò)誤，是指通過(guò)top校驗(yàn)進(jìn)入后端調(diào)用服務(wù)以后，由于不符合進(jìn)一步的業(yè)務(wù)邏輯校驗(yàn)而出現(xiàn)的錯(cuò)誤。如：發(fā)布商品的屬性不符合商品類目的要求，評(píng)價(jià)的交易已經(jīng)過(guò)期等等。這些錯(cuò)誤在2.0的返回子錯(cuò)誤碼為：XXX-service-error。用戶遇到這種返回表明top的服務(wù)是正常的，是用戶的參數(shù)不合規(guī)定所引起。請(qǐng)根據(jù)返回的具體msg和sub_msg內(nèi)容定位問(wèn)題，然后改正入?yún)⒑笤僬{(diào)用。如果確認(rèn)參數(shù)正確卻一直通不過(guò)調(diào)用，請(qǐng)聯(lián)系技術(shù)支持的同學(xué)咨詢情況，切勿盲目重試。b) 服務(wù)調(diào)用異常服務(wù)調(diào)用異常是指服務(wù)調(diào)用過(guò)程中由于后端服務(wù)器沒(méi)有響應(yīng)或者產(chǎn)生了異?；蛘遲op

46、服務(wù)本身產(chǎn)生了未被捕獲的異常而產(chǎn)生的錯(cuò)誤。這些錯(cuò)誤在2.0的返回子錯(cuò)誤碼為：XXX-service-unavailable。這種錯(cuò)誤有可能是后端服務(wù)暫時(shí)不可用所引起的，所以用戶遇到這種錯(cuò)誤時(shí)首先應(yīng)該查看返回的錯(cuò)誤信息里面有沒(méi)有有效的提示信息，如果有請(qǐng)先按照提示改正問(wèn)題再調(diào)用；如果沒(méi)有有效的提示信息，請(qǐng)等待一段時(shí)間再調(diào)用。如果一直都是這個(gè)錯(cuò)誤，請(qǐng)聯(lián)系技術(shù)支持查看問(wèn)題所在。切忌立即反復(fù)重試。c) 遠(yuǎn)程調(diào)用錯(cuò)誤遠(yuǎn)程調(diào)用錯(cuò)誤是指top在調(diào)用后方服務(wù)時(shí)發(fā)生了調(diào)用錯(cuò)誤或超時(shí)的情況。這類錯(cuò)誤可能是由于后端服務(wù)過(guò)于繁忙或者服務(wù)失效引起的。這些錯(cuò)誤在2.0的返回子錯(cuò)誤碼為：remote-service-erro

47、r，remote-service-timeout，remote-connection-error。用戶遇到這種情況，首先考慮的是等待一段時(shí)間重試看服務(wù)是否恢復(fù)。如果服務(wù)已經(jīng)恢復(fù)，則這個(gè)只是短時(shí)間服務(wù)過(guò)于擁擠造成的；如果多次重試仍然是不可用，那么這個(gè)可能是后端服務(wù)出了問(wèn)題，請(qǐng)聯(lián)系技術(shù)支持進(jìn)行處理。d) Top解析錯(cuò)誤Top解析錯(cuò)誤目前主要針對(duì)的是用戶調(diào)用top服務(wù)時(shí)產(chǎn)生的未被捕獲的空指針或者參數(shù)轉(zhuǎn)換異常所產(chǎn)生的錯(cuò)誤。這些錯(cuò)誤是由于用戶的請(qǐng)求有錯(cuò)誤引發(fā)了top本身的服務(wù)流程的潛在隱患所引起的。在2.0的返回子錯(cuò)誤碼為：top-parse-error。用戶遇到這種問(wèn)題時(shí)，請(qǐng)先仔細(xì)檢查自己的參數(shù)，根據(jù)

48、文檔說(shuō)明修改完善以后再嘗試調(diào)用，一般正常情況，只要入?yún)⒑戏ㄊ悄軌虺晒Φ摹Ｈ绻_定參數(shù)正確的前提下還是調(diào)用報(bào)這個(gè)錯(cuò)誤，請(qǐng)聯(lián)系技術(shù)支持的同學(xué)反饋這個(gè)問(wèn)題。六、 返回參數(shù)缺失處理返回參數(shù)缺失是指用戶調(diào)用api返回成功，但是消息體里面的內(nèi)容和所請(qǐng)求的內(nèi)容不一致的情況。這種情況細(xì)分可以分為三種情況：整個(gè)消息體為空、消息體缺少文檔定義的結(jié)構(gòu)返回、返回的結(jié)構(gòu)體中缺少fields指定的某些字段的返回。1. 整個(gè)消息體為空或缺少文檔中說(shuō)明的結(jié)構(gòu)體返回。整個(gè)消息體為空或缺少文檔中說(shuō)明的結(jié)構(gòu)體是指：返回結(jié)果是非失敗的情況下，得到的Response的body內(nèi)容和文檔定義不一致（比文檔寫(xiě)到要缺少某些內(nèi)容）的情況。例如：調(diào)用新增商品接口，正常的2.0的返回結(jié)果是："item_add_response":"item":"iid":"699e0a75fcea3966d1d57fc8278c674b","created":"2009-10-22 15:08:42"。根據(jù)文檔的說(shuō)明：添加商品成功的返回結(jié)構(gòu)體中包含的數(shù)據(jù)就是這樣。以此種返回結(jié)果舉例，整個(gè)消息體為空的