top错误诊断说明Word格式.docx

1、这三种类型的错误分别代表了：淘宝服务器、淘宝接入平台、top-api业务，几个层次上出现的问题。1）?http连接错误http连接错误是请求通信过程中出现的错误，这类型错误通常由http响应码标记出来。http响应码由三位十进制数字组成，它们出现在由HTTP服务器发送的响应的第一行。响应码分五种类型，由它们的第一位数字表示：1xx：信息，请求收到，继续处理2xx：成功，行为被成功地接受、理解和采纳3xx：重定向，为了完成请求，必须进一步执行的动作4xx：客户端错误，请求包含语法错误或者请求无法实现5xx：服务器错误，服务器不能实现一种明显无效的请求Isv调用top服务最常收到就是200：htt

2、p请求成功；404：未找到请求的服务；500内部服务器错误等等。如果用户收到的响应码是404，表示用户的网络有问题或者top被和谐了如果用户收到的响应码是500，表示网络是ok的，是top的服务无法响应。2）?服务端错误总述平台解析错误和业务处理错误都是http成功访问到top服务（http响应码返回为200）之后所产生的错信息，他们top处理isv请求过程中出现的问题。1.0和2.0的格式有所不同。1.0的错误响应信息最外层为“error_rsp”:,表示这是调用错误所返回的信息。里面一层包含两个元素：”code”:”和“msg”:”，前者表示错误码是多少，后者表示错误信息是什么。例如错误的

3、调用1.0的服务错误时返回的错误信息：error_rspcode40,msgMissingrequiredarguments:missingparameteriid/num_iid。这个信息的开头为error_rsp，表示这是调用错误所返回的结果。里面包含的错误体的code为40，是平台型错误，表示错误是缺少了必传参数所引起的。然后msg内容为Missingrequiredarguments:missingparameteriid/num_iid，表示缺少的必传参数是iid或者num_iid。Isv解析到这些信息后就需要根据错误信息改进自己传入的参数来使调用成功。2.0的错误响应信息的最外层为

4、“error_response”:”，表示这是调用服务失败所返回的错误信息。信息体里面一层总共包含了五个元素：argsarg“key”:“”,”value”:”,“key”:”，”code”:”，“msg”:”，”sub_code”:”和”sub_msg”:”。args表示用户传入的参数列表是什么，里面是一个arg的列表会包含用户传入的所有参数信息，每个arg表示一个参数的信息，key表示参数的名称，value表示参数的内容，用以方便用户定位自己的错误；code表示用户调用错误的错误码是多少，小于200表示平台级错误，200-1000之间表示大范围的业务错误，即哪一类型的api调用发生了错误（

5、根据api的大类来分，如：商品类的api是530，交易类的api是520，等）；msg表示大类型的错误码所对应的错误信息，一般不具备独立的debug作用，需要和sub_code和sub_msg一起使用才行；sub_code是调用错误的子错误码，他表示用户调用错误的原因；sub_msg是子错误码所对应的错误信息，他用来补充细化子错误码的错误原因的。例如调用2.0的服务错误时返回的错误信息：tner_id,valueTOPTEST,keysign668FB4A049F71A1C845EF8C05B1F3E66timestamp2010-03-0518:03:06.325v2.0,530,Remot

6、eserviceerrorsub_codemissing-parametersub_msgiid和num_iid至少要传入一个这个信息的开头为error_response，表示这是调用错误所返回的错误信息。里面的args列出了用调用这个接口传入的信息有：nicktbtest561partner_id，这些信息是从用户的请求信息里面解析出来的。错误码code为530，表示这是调用商品的api所产生的错误。错误信息msg为Remoteserviceerror表示这是调用业务处理所产生的错误。子错误码sub_code为：missing-parameter，表示这个错误是因为缺少了参数所产生的。子错误

7、信息sub_msg为：iid和num_iid至少要传入一个，表示少传的参数为iid或num_iid。这所有的错误信息叠加起来可以知道，这个错误是用户调用接口时业务处理发现用户没有传入商品id所导致的。3）?平台解析错误平台解析错误是指top返回的错误码小于100的情况。平台解析是非业务性的普适的校验接入层，主要用于对用户的各种权限、和入参进行最基本的校验。现在的平台错误码主要有：Isv可以通过错误码和解释来纠正问题。如：错误码为3的响应表示图片上传失败，错误码为26表示用户没有传入session参数，错误码为27表示用户传入的session参数找不到对应的session记录，等等。4）?业务处

8、理错误业务处理错误是用户通过平台校验进入业务流程出现了错误所发出来的。这一层的错误码根据调用版本不同分为两种。如果版本是1.0，那么返回的错误信息格式就是：“error_rsp”:“code”:XXX,”msg”:”，里面的code是数字形式的标记着一种错误的编码，msg是字符串形式，标记在错误的具体信息。如，获取当商品失败的错误信息就是：551,Itemserviceunavailable:获取单个商品失败1.0的错误码有以下几种：1.0的返回的错误code就是其中的错误码，错误msg就是其中的英文错误描述加上具体的错误信息组成的。如果版本是2.0，那么服务器所返回的错误信息格式就是：“er

9、ror_response”:”,”code”:”,“msg”:”,”sub_code”:”,”sub_msg”:”，里面的code是数字形式的标记着一种业务类型的错误编码，msg则是比较大范围内的表示错误类型的字符串。而sub_code是以字符串形式粗略表示错误的类型，sub_msg则是表示具体的错误原因。2.0的code包含以下几种分类：产品线错误码用户500类目510交易520退款521商品530商品扩展API531邮费模板532产品540物流550店铺560评价570淘宝客580系统590备案591增量API600比价610画报620江湖630分销640淘秀650收费660Misc（保证

10、金等杂项api）670由上图可知，每一大类的api在2.0中其实是共享一个code的，它能让用户在复杂组合调用中指导是哪一类的api出现了问题，实现初步的定位。2.0的业务错误中，msg里面最容易出现的内容就是Remoteserviceerror，这表示用户是在通过了平台校验后进行业务流程的时候出现的错误。其他的错误还有RemoteServiceTimeout：后台处理业务超时等等的错误。这一个错误信息的力度比较粗，很难单独用她进行错误处理。2.0的业务处理错误信息主要要看sub_code和sub_msg这连个字段。sub_code表示了服务费对业务错误的分类，sub_msg表示了是错误原因。

11、Sub_code根据业务错误类型主要可以分为如下几类子错误码错误归类user-not-exist用户不存在missing-parameter缺少参数invalid-parameter参数错误parameters-mismatch参数不匹配（主要针对那些需要一一对应的入参）Invalid-permission权限不足remote-service-error调用后端服务错误remote-service-timeout调用后端服务超时remote-connection-error调用后端服务连接错误XXX-service-unavailable调用后端服务失败item-extra-not-exist

12、商品扩展信息不存在trade-not-exist交易记录不存在refund-not-exist退款记录不存在每一类的子错误码代表着某一类型的错误，例如user-not-exist表示用户传入的nick或者用户绑定的session所对应的nick找不到对应的用户记录，Invalid-permission表示用户由于权限问题不能进行某些操作。sub_code给予isv或用户以改进错误的方向，而sub_msg则告诉用户改进点。例如sub_code为invalid-parameter，sub_msg为用户传入的iid不能超过40个，这就表示着，这次错误的原因是用户传入的参数iid由于数量超过40个而产

13、生了错误。错误响应时用户和服务器交互失败的最直接展示，isv在调用top服务时，如果调用失败，请尽量保留下错误信息（建议尽量改用2.0调用，这个版本的错误信息比较全面），以便进行后面的错误追查。三、?响应格式错误处理响应格式错误是指用户调用top服务时，传入参数设置了format参数为json，但是接受到的却为xml的响应格式，或者设置格式为xml接收到的却为json响应的格式的情况。一般正常情况下这种情况是不会出现的，但是还是会有一些异常的情况会引起这个问题。这种响应格式错误的问题在isv的程序中通常会表现为，响应解析格式错误。例如：用户使用的top的javaSDK客户端调用top服务，设置

14、的format格式为json却得到了一个xml的响应，这是sdk就会报一个错误说响应开始处缺少一个“”符号。这是因为xml响应是以“”开始的缘故。一般会发生这种现象的原因有一下三种：用户传入的参数过大导致流解析异常，用户调用太过频繁道士响应异常，top服务器故障。为了定位到问题出在哪里，以便找到相应的解决方法，用户在遇到响应格式错误的情况时可以参考以下步骤进行调试。响应格式格式错误，但数据正确用户第一步应该分析一下相应的内容里面是不是除了格式错误以外，其他的响应内容都是正确调用的返回结果。例如，有个用户用top的sdk，设置format为json，调用top得到了这样一个返回结果：A?JSON

15、Object?text?must?begin?with?at?character?1?rsptotalResults1115itemiid!CDATA77a003aef35f8d959eef03d7ba3d23e3/iidmodified2010-03-01?16:04:15/itemCDATAc559afab73ab721a8e7500b62864add005595307:30:52从这个异常的开头可以看到，这是sdk的json解析抛了一个异常，说响应内容的内容应该是以“”开始的。这说名，isv收到的响应格式肯定出了问题。再看一下响应的内容相应结果标签之间包含了totalResults和it

16、em列表，这些数据表明，这是调用商品查询接口返回的结果数据：查询到的结果总数是1115条，当前页的商品iid和最近修改时间也在其中。这些查询结果数据是正常的，但是返回格式却不是传入的json而是变成了xml。这位isv联系了top的技术支持，在建议减缓调用频率以后，返回的数据格式正常了，这样就临时控制了这种情况的发生。同时技术支持将这些情况反映到了开发，top这边后续就会找到问题根源，进一步杜绝这种情况的发生。响应格式错误，数据也错误如果用户第一步分析发现，返回的信息并不是调用成功的信息而是某个平台错误，而且用户本身的参数并不会导致这个错误的产生，此时用户就需要查看自己调用接口的参数了。如果用

17、户调用的接口需要传入比较大的数据（如：图片、商品的长篇描述等等），那么用户应首先尝试着减小这些入参到合法范围内输入（传入小图片或者之传入少量的描述文字等）。如果用户调用成功，表示错误是因为用户入参太大造成了解析错误引起的，用户应配合自己所在地方的网速，请求大小等等的信息合理设置自己的参数大小和接口调用顺序。如果用户减小参数还是解析失败的话，用户尝试着不传入图片或只传入几个字节的描述的内容进行接口调用。在传入描述只有很少的字节的情况下：如果不传图片调用成功了，那么应该是top的服务器的问题，请将这个情况反馈给技术支持进行解决；如果图片不传调用仍然失败了，那么应该是用户的调用参数或网络有问题，请仔

18、细对照文档说明对参数进行修改或等待网络状态好一点的时候进行调用。总的来说，如果用户发生了响应格式错误的情况，一般分为三种情况：用户本身传入的format就是错误的，这种情况用户需要查看自己传入的参数是否正确；用户通信的网络太差，服务端造成请求解析失败而丢失了format信息，这种情况下用户需要调整自己的网络通信情况，等状况恢复再调用；如果是其他由于图片或调用太频繁而引起的问题，用户需要减小图片或减缓调用来提高成功率，并且将这些情况通报给top技术支持的同学。四、?平台级错误处理在前文的错误综述中介绍过，top的错误可以分为平台级错误和业务级错误。所谓平台级错误就是指：错误码小于100的调用错误

19、。这种错误一般是由于用户的请求不符合各种的基本校验而引起的。下面将对于各种平台级错误及相应的解决办法陈列于此。错误解释解决办法3图片上传失败将传入的图片格式改为正确的格式、适当的大小的图片放进消息体里面传输过来。如果传输仍然失败需要减小图片大小或者增加网络带宽进行尝试4用户调用次数超限调整程序逻辑合理利用api，等第二天再调用。或者向技术运维的同学申请增加调用次数5会话调用次数超限6合作伙伴调用次数超限7应用调用次数超限8应用调用频率超限Isv调节api调用频率，不能太过频繁的调用9HTTP方法被禁止请用大写的POST或GET，如果有图片等信息传入则一定要用POST才可以10服务不可用多数是由

20、未知异常引起的，用户仔细检查自己传入的参数是否符合文档中描述的样子11开发者权限不足appKey所对应的应用不具备权限调用当前接口。需要联系运营或技术支持的同学开通调用该接口的权限。12用户权限不足13合作伙伴权限不足15远程服务出错Api调用后端服务出错，isv首先查看自己的参数是否合法，如果参数没有问题请过一段时间再尝试，如果还不行请联系技术支持21缺少方法名参数传入的参数加入method字段22不存在的方法名传入的method字段必需是你所调用的api的名称，并且该api是确实存在的23非法数据格式传入的format必需为json或xml中的一种24缺少签名参数传入的参数中必需包含sig

21、n字段25非法签名签名必需根据正确的算法算出来的。算法请见：26缺少SessionKey参数传入的参数中必需包含session字段27非法的SessionKey参数传入的session必需是用户绑定session拿到的。如果报session不合法可能是用户没有绑定session或session过期造成的，用户需要重新绑定一下然后传入新的sessionKey。28缺少AppKey参数传入的参数必需包含app_key字段29非法的AppKey参数用户传入的appKey参数确实是要存在的，如果没有申请appKey的同学请去申请appKey，如果是已经有了appKey却调用不同过的，请联系技术支持解决

22、30缺少时间戳参数传入的参数中必需包含timestamp参数31非法的时间戳参数用户传入的时间戳不合法。时间戳，格式为yyyy-mm-ddhh:mm:ss，例如：2008-01-2520:23:30。淘宝API服务端允许客户端请求时间误差为10分钟。32缺少版本参数传入的参数中必需包含v字段33非法的版本参数用户传入的版本号格式错误，必需为数字格式34不支持的版本号用户传入的版本号没有被提供。现在top只支持1.0或2.0两种版本40缺少必选参数用户传入的参数中漏掉了必传的参数。请仔细对照文档检查41非法的参数用户传入的参数不符合文档中说明的参数格式，请参照文档进行修改42请求被禁止请求被禁止

23、（目前没有在控制）43参数解析发生错误或异常。一般是用户传入参数非法引起的。请仔细检查入参格式、范围、是否一一对应等等情况。44Isperror后台接入服务错误这种后台服务异常引起的错误，请联系技术支持。基本上来说，平台错误是一个通用的、普适的校验。一般针对用户的权限、安全、流量和最基本的参数等等进行校验。用户遇到这些错误的返回一定要第一步检查自己的权限、频率等情况；然后就需要参照文档检验一下自己的传入的参数是否完整且合法；如果这些都无法解决问题，请联系技术支持的同学进行反馈，top后台会尽快解决这些问题。五、?业务级错误处理业务级错误是指isv请求进入top业务处理以后爆出来的业务相关的错误

24、，通常错误码分部在500-1000之间。Top的业务错误一般可以分为4个大类：参数错误、权限控制、用户不存在和服务错误。参数错误指topapi根据业务要求对用户传入的参数进行校验组装的时候产生的错误。1.0中的参数错误码有：505,MissingParameters;506,Parameterserror507,ParametersFormaterror和XXX,”XXXnotexist”（这里XXX表示未知的数字或字符串）等等。其中：505表示缺少传入某些需要传入的参数（如：获取sku列表的时候要求至少传入一个iid，isv却什么都没有传入）;506表示传入的参数错误（如：传入的iid找到对应的商品已删除、传入的类目不存在等等）；507表示用户传入的参数的格式不符合规定（如：需要传入数字的参数用户传入了非数字的字符）；XXXnotexist表示根据用户指定的参数（如：iid、tid等数据）找不到对应的记录，等等。2.0中的参数错误的错误码是在调用返回的sub_code子错误码里面得到具体体现的。2.0的参数错误一般有如下几个错误码：missing-parameter，invalid-parameter，parameters-mismatch，XXX-not-exist等等。这几种错误分