開放平臺錯誤自查手冊具體錯誤墨靈

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

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

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

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

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

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

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

8、的錯誤原因的。例如調用2.0的taobao.item.get服務錯誤時返回的錯誤信息："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至少要傳入一個"這個信息的開頭為error_response，表示這是調用錯誤所返回的錯誤信息。里面的args列出了用調用這個接口傳入的信息有："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、請求信息里面解析出來的。錯誤碼code為530，表示這是調用商品的api所產生的錯誤。錯誤信息msg為Remote service error表示這是調用業(yè)務處理所產生的錯誤。子錯誤碼sub_code為：missing-parameter，表示這個錯誤是因為缺少了參數(shù)所產生的。子錯誤信息sub_msg為：iid和num_iid至少要傳入一個，表示少傳的參數(shù)為iid或num_iid。這所有的錯誤信息疊加起來可以知道，這個錯誤是用戶調用taobao.item.get接口時業(yè)務處理發(fā)現(xiàn)用戶沒有傳入商品id所導致的。3) 平臺解析錯誤平臺解析錯誤是指top返回的錯誤碼小于100的情況。平臺解析是非業(yè)務

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

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

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

18、 缺少版本參數(shù) 平臺本身33Invalid Version 非法的版本參數(shù) ISV34Unsupported Version 不支持的版本號 ISV40Missing Required Arguments 缺少必選參數(shù) 平臺本身41Invalid Arguments 非法的參數(shù) ISV42Forbidden Request 請求被禁止 ISV43Parameter Error 參數(shù)錯誤 ISV 圖表 2 平臺錯誤碼列表Isv可以通過錯誤碼和解釋來糾正問題。如：錯誤碼為3的響應表示圖片上傳失敗，錯誤碼為26表示用戶沒有傳入session參數(shù)，錯誤碼為27表示用戶傳入的session參數(shù)找不到對應

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

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

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

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

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

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

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

26、戶在遇到響應格式錯誤的情況時可以參考以下步驟進行調試。圖表 5 響應格式錯誤處理流程1. 響應格式格式錯誤，但數(shù)據正確用戶第一步應該分析一下相應的內容里面是不是除了格式錯誤以外，其他的響應內容都是正確調用的返回結果。例如，有個用戶用top的sdk，設置format為json，調用top得到了這樣一個返回結果：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>從這個異常的開頭可以看到，這是sdk的json解析拋了一個異常，說響應內容的內容應該是以“”開始的。這說名，isv收到的響應格式肯定出了問題。再看一下響應的內容<rsp></rsp>相應結果標簽之間包含了totalResults和item列表，這些數(shù)據表明，這是調用商品查詢接口返回的結果數(shù)據：查詢到的結果總數(shù)是1115條，當前頁的商品iid和最近修改時間也在其中。這些查詢結果數(shù)據是正常的，但是返回格式卻不是傳入的json而是變成了xml。這位isv聯(lián)系了top的技術支持，在建議減緩調用頻率以后，返回的數(shù)據格式正常了，這樣就臨時控制了這種情況的發(fā)生。同時技

31、術支持將這些情況反映到了開發(fā)，top這邊后續(xù)就會找到問題根源，進一步杜絕這種情況的發(fā)生。2. 響應格式錯誤，數(shù)據也錯誤如果用戶第一步分析發(fā)現(xiàn)，返回的信息并不是調用成功的信息而是某個平臺錯誤，而且用戶本身的參數(shù)并不會導致這個錯誤的產生，此時用戶就需要查看自己調用接口的參數(shù)了。如果用戶調用的接口需要傳入比較大的數(shù)據（如：圖片、商品的長篇描述等等），那么用戶應首先嘗試著減小這些入參到合法范圍內輸入（傳入小圖片或者只傳入少量的描述文字等）。如果用戶調用成功，表示錯誤是因為用戶入參太大造成了解析錯誤引起的，用戶應配合自己所在地方的網速，請求大小等等的信息合理設置自己的參數(shù)大小和接口調用順序。如果用戶減小

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

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

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

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

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

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

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

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

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

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

42、不是信息的合法查看人，那么isv要明確的告訴用戶這個操作不可以進行，并且不要進行重試操作了。第二：對于增刪改類型的操作的權限控制：如果用戶是因為沒有享有服務（如：沒有享有圖片空間的服務）而產生的權限限制，isv需要引導用戶去進行服務的開通后再來進行操作，之后再重新調用接口；如果是因為用戶操作了別人的數(shù)據而引起的權限控制，那么isv要明確的跟用戶報錯，并且不能再進行重試操作。總之，當用戶遇到報權限控制的錯誤時，isv不能直接進行重試。應該將問題直接告訴用戶，并引導用戶進行相關的登錄、開通服務等操作來調整權限以后，再讓用戶重試操作。如果用戶不愿意進行調整，isv此時應該直接停止該操作，不能默認的進

43、行重試，因為這種前提下，重試是完全沒有作用的。3. 用戶不存在用戶不存在是指top后臺根據用戶綁定的nick或者傳入的nick對用戶信息進行查詢的時候找不到用戶記錄所報出的錯誤。2.0的子錯誤碼：user-not-exist。用戶遇到這種問題首先請確認調用的這個接口自己有沒有傳入nick這個參數(shù)。如果nick是根據用戶綁定的session取得的，那么用戶需要過一會兒再重新調用看看。如果隔一段時間還不行，請聯(lián)系技術支持解決。如果用戶自己通過參數(shù)傳入了nick，那么請用戶仔細檢查自己傳入的nick是否正確。例如：有沒有多一個空格或者大小寫錯誤的？該用戶是否確實存在的？等等。如果問題是因為名稱錯誤或

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

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

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

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

48、文檔說明修改完善以后再嘗試調用，一般正常情況，只要入參合法是能夠成功的。如果確定參數(shù)正確的前提下還是調用報這個錯誤，請聯(lián)系技術支持的同學反饋這個問題。六、 返回參數(shù)缺失處理返回參數(shù)缺失是指用戶調用api返回成功，但是消息體里面的內容和所請求的內容不一致的情況。這種情況細分可以分為三種情況：整個消息體為空、消息體缺少文檔定義的結構返回、返回的結構體中缺少fields指定的某些字段的返回。1. 整個消息體為空或缺少文檔中說明的結構體返回。整個消息體為空或缺少文檔中說明的結構體是指：返回結果是非失敗的情況下，得到的Response的body內容和文檔定義不一致（比文檔寫到要缺少某些內容）的情況。例如：調用新增商品接口，正常的2.0的返回結果是："item_add_response":"item":"iid":"699e0a75fcea3966d1d57fc8278c674b","created":"2009-10-22 15:08:42"。根據文檔的說明：添加商品成功的返回結構體中包含的數(shù)據就是這樣。以此種返回結果舉例，整個消息體為空的