API异常排查方法
一、快速排查问题
1、快速排查问题流程图
附:API文档地址://open.taobao.com/api/api_list.htm?spm=a219a.7386781.0.0.g5ZY6Y
规则中心地址://open.taobao.com/doc/detail.htm?id=101612
淘宝客服联系方式: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问题
开发者发送HTTP请求淘宝数据之前的出现的问题,包括淘宝业务问题,商务问题,容器类错误问题。
1. 淘宝业务问题:
(1)业务规则问题,比如:商品或用户被处罚等
(2)在淘宝页面操作不成功的问题,比如:在淘宝后台无法查看出售中的商品等
2. 商务问题:
(1)应用接入问题,比如:一个开发者可以注册多少个应用等
(2)应用审核问题,比如:哪些应用不支持接入等
(3)应用上线问题,比如:调用频率是如何限制的等
3. 容器类错误问题:
通过容器,用户可以授权开发者获取其数据信息,主要是页面上错误码在100到200之间的错误。
API问题
开发者发送HTTP请求淘宝数据之后的出现的问题,包括HTTP连接错误问题,平台级错误问题,业务级错误问题,这三种类型的错误问题分别是在访问淘宝服务器,TOP接入平台,淘宝后端业务服务器这三个层次上出现的问题。
1. HTTP连接错误问题:
请求淘宝服务器过程中出现的错误,这类型错误通常由HTTP响应码标记出来,HTTP响应码由三位十进制数字组成,它们出现在由HTTP服务器发送的响应的第一行。响应码分五种类型,由它们的第一位数字表示:
1xx:信息,请求收到,继续处理
2xx:成功,行为被成功地接受、理解和采纳
3xx:重定向,为了完成请求,必须进一步执行的动作
4xx:客户端错误,请求包含语法错误或者请求无法实现
5xx:服务器错误,服务器不能实现一种明显无效的请求
开发者调用TOP服务最常收到就是200:http请求成功;404:未找到请求的服务;500内部服务器错误等。如果开发者收到的响应码是404,表示用户的网络有问题,如果开发者收到的响应码是响应码是500,表示网络是正常的但是top的服务无法响应。
如果是本地网络有问题可以直接输入命令行ping gw.api.taobao.com测试请求淘宝服务器的速度,如果速度很慢则要考虑服务器提速的问题,如果ping不通,则联系网络管理员确认服务器是否屏蔽淘宝域名。
2. 平台级错误问题:
请求TOP接入平台出现的错,此时TOP返回的错误码小于100,这种错误一般是由于用户的请求不符合权限,安全,流量和最基本的参数等校验引起的。
3. 业务级错误问题:
请求后端业务服务器出现的问题,返回的错误码在500到1000之间,具体子错误码及解决方案可参见API文档。
2、排查问题详细流程图
详细描述开发者发现以上问题之后的处理流程。
3、快速排查问题范例
我从错误日志中分析出来taobao.item.recommend.add报isv.item-recommend-service- error:ERROR_MORE_THAN_ALLOWED_RECOMMEND_NUM(超过橱窗推荐总数)错误很多,该如何解决呢?
首先根据排查问题流程定位到API问题,再查看API文档中的错误码解决方案:
1. 橱窗推荐的时候要求用户输入橱窗推荐总量,有的用户会多输,所以报橱窗推荐超过最大推荐数的错误,每天定时更新橱窗总量,橱窗总量=已推荐橱窗+剩余橱窗(不能完全杜绝这个错误)
2. 开发者先调用taobao.shop.remainshowcase.get 接口获取卖家的剩余橱窗数,做好逻辑判断,再调用橱窗推荐的接口。
范例2
本地程序报连接重置错误且没有top的错误码返回,这类问题该如何解决?
建议:
1.合理切割任务,将任务粒度放小,减小事务时间,提高事务执行成功率,降低回滚代价;
2.合并任务中重复的内容,在时间间隔容许的范围内,减少可能重复的操作;
3.看是否有批量操作接口,减少单个循环调用次数;
4.控制工作线程池线程个数,根据实际性能和对方服务器处理能力设置并行任务个数:
线程并发开的越多未必成功率越高!
首先本地资源有限(开的越多线程,本地GC回收频率越高,影响执行速度,效率反而降低);
其次,对方可能会由于你的ip连接数过多主动拒绝连接;(DOS保护)
再次,信道无法复用。(当前1.6JDK版本已经能够较好的复用TCP信道,并发瞬间开大量的TCP信道本身就是一种损耗,有时候部分串行化,某种程度上会减少产生TCP信道的数目合理利用信道,提高效率和成功率,客户端做好流控也很重要)
范例3
网络丢包问题解决方案:
问题背景:
1.由于互联网物理线路可靠性不是100%,ISV服务器到TOP之间的通信存在数据丢失情况
2.开发者需要一种方法来验证每次访问取得的数据是不是完整的,有没有丢包
3.目前有的ISV通过这样的方法校验完整性:连续多次调用API,并比较返回结果,若完全相同,则认为是完整的。这种方法不可靠(多次调用本来就有可能返回不同的业务结果),增加了ISV开发成本,也加重了TOP的服务器压力
解决方案:
为了解决开发者反馈的ISV校验数据完整性的问题,TOP已经在HTTP Header中加入一个新的元素:top-bodylength。
使用方法:开发者取到这个top-bodylength的值,计算一下收到的HTTP Body长度,如果两者相等,则说明返回的数据是完整的,如果计算出来HTTP Body的长度小于top-bodylength的值,说明发生了丢包。
注:
1:TOP没有改HTTP Body,所以,不会对已有应用造成任何影响。
2:top-bodylength是表示HTTP Body的个String字符长度(不区分中文英文,都算作1个长度)
二、错误码一览表
1.目前开发者调用API可能出现的错误有三类:API平台错误、ISV业务错误和容器类错误。下面介绍一下和ISV成功率有关的名词说明:
有效访问量=成功访问量+ISV业务错误 (成功访问指的是正常获取到数据并且无报错的调用)
ISV成功率=成功访问量/有效访问量
2.连接淘宝服务器错误主要是http连接错误或者连接被重置被拒绝等,这类错误是开发者访问淘宝服务器出现的问题,请直接联系服务器管理员或通过网络搜索答案。
1、API平台错误
API平台错误是主要包含两类错误:
(1)错误码小于100(不包含15,40,41错误码)的调用错误,这种错误一般是由于用户的请求不符合各种基本校验而引起的。用户遇到这些错误的返回首先检查应用的权限、频率等情况,然后参照文档检验一下传入的参数是否完整且合法。
(2)子错误码(sub_code)是"isp."开头的调用错误,这种错误一般是由于服务端异常引起的。用户遇到这类错误需要隔一段时间再重试就可以解决。
错误码小于100的平台级错误
错误码错误描述-英文错误描述-中文解决方案3Upload Fail图片上传失败将传入的图片格式改为正确的格式、适当的大小的图片放进消息体里面传输过来,如果传输仍然失败需要减小图片大小或者增加网络带宽进行尝试7App Call Limited应用调用次数超限,包含调用频率超限调整程序合理调用API,等限频时间过了再调用,淘客的调用频率是系统按照上个月交易额自动修改的,修改后的频率会在官方论坛首页以公告形式通知,开发者可自行查看9Http Action Not AllowedHTTP方法被禁止请用大写的POST或GET,如果有图片等信息传入则一定要用POST才可以10Service Currently Unavailable服务不可用多数是由未知异常引起的,仔细检查传入的参数是否符合文档描述11Insufficient ISV Permissions开发者权限不足子错误码目前有isv.permission-api-package-empty 没有和任何访问包关联,建议根据业务规则申请对应的权限isv.permission-api-package-not-allowed 不允许访问不可访问组的API,建议检查一下自己申请的应用标签是否正确,如果确实需要访问不可访问组的API需要根据业务规则到对应的业务线申请权限 例如:买家不可访问组就会有一些订单API不允许买家应用访问isv.permission-api-package-limit 关联的包中不允许访问该API,建议根据业务规则申请对应的权限isv.permission-ip-whitelist-limit IP限制不允许访问,建议到安全中心配置正确的IP白名单isv.permission-api-widget-only-limit 仅允许widget(组件)方式访问12Insufficient User Permissions用户权限不足应用没有权限调用增值权限的接口,可在淘宝合作伙伴后台提交权限申请13Insufficient Partner Permissions合作伙伴权限不足应用没有权限调用增值权限的接口,可在淘宝合作伙伴后台提交权限申请21Missing Method缺少方法名参数传入的参数加入method字段22Invalid Method不存在的方法名传入的method字段必需是你所调用的API的名称,并且该API是确实存在的23Invalid Format无效数据格式传入的format必需为json或xml中的一种24Missing Signature缺少签名参数传入的参数中必需包含sign字段25Invalid Signature无效签名签名必需根据正确的算法算出来的。算法请见://open.taobao.com/doc/detail.htm?id=101617#ss226Missing Session缺少SessionKey参数传入的参数中必需包含session字段27Invalid Session 、 unmix-sessionkey-failure无效的SessionKey参数传入的session必需是用户绑定session拿到的,如果报session不合法可能是用户没有绑定session或session过期造成的,用户需要重新绑定一下然后传入新的sessionKey28Missing App Key缺少AppKey参数传入的参数必需包含app_key字段29Invalid App Key无效的AppKey参数应用所处的环境跟选择的环境不一致,例如:应用处于沙箱测试环境,却选择在正式环境进行测试。30Missing Timestamp缺少时间戳参数传入的参数中必需包含timestamp参数31Invalid Timestamp非法的时间戳参数时间戳,格式为yyyy-mm-dd hh:mm:ss,例如:2008-01-25 20:23:30。淘宝API服务端允许客户端请求时间误差为10分钟32Missing Version缺少版本参数传入的参数中必需包含v字段33Invalid Version非法的版本参数用户传入的版本号格式错误,必需为数字格式34Unsupported Version不支持的版本号用户传入的版本号没有被提供42Insufficient session permissions短授权权限不足调用的是高危API,请参考安全等级文档//open.taobao.com/doc/detail.htm?id=100243Parameter Error参数错误一般是用户传入参数非法引起的,请仔细检查入参格式、范围是否一一对应44Invalid access token无效的access token一般是用户使用top协议获取的sessionkey当做access token通过https方式调用API或调用环境搞错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解析错误(出现了未被明确控制的异常信息)ISP否isp.top-remote-connection-timeouttop平台连接后端服务超时ISP是isp.top-remote-connection-errortop平台连接后端服务错误,找不到服务ISP是isp.top-mapping-parse-errortop-mapping转换出错,主要是由于传入参数格式不对ISP否isp.unknown-errortop平台连接后端服务抛未知异常信息ISP是 |
2、ISV业务错误
1.ISV业务级错误是ISV传入的参数缺失,有误或格式错误等原因造成的错误。因此isv应该根据错误信息检验是否传入了相应的信息,对于这一类错误建议改正后再重试。
主要包含两类:
(1)错误码为40,41的错误;40主要是必填参数没有传入报错,41主要是传入的参数格式不对报错。:2.
(2)错误码大于100或者等于15且子错误码(sub_code)是"isv."开头【( 错误码 > 100 or 错误码 = 15 ) and (isv开头)】的调用错误:
2.错误响应是用户和服务器交互失败的最直接展示,isv在调用top服务时,如果调用失败,请尽量保留下错误日志以便进行后面的错误追查。
3、40/41错误介绍
错误码错误描述-英文错误描述-中文解决方案40Missing Required Arguments缺少必选参数API文档中设置为必选的参数是必传的,请仔细核对文档41Invalid Arguments非法的参数参数类型不对,例如:需要传入的是数字类型的,却传入了字符类型的参数 |
4、业务级子错误
子错误码格式错误信息归属方是否可在程序中重试isv.###-not-exist:***根据***查询不到###ISV否isv.missing-parameter:***缺少必要的参数***ISV否isv.invalid-paramete:***参数***无效,格式不对、非法值、越界等ISV否isv.invalid-permission权限不够、非法访问ISV否isv.parameters-mismatch:***-and-###传入的参数***和###不匹配,两者有一定的对应关系ISV否isv.***-service-error:###调用***服务返回false,业务逻辑错误,###表示具体的错误信息ISV否 |
3、安全等级和安全漏洞错误码
父错误码信息
错误码 | 英文描述 | 中文描述 | 解决方案 |
53 | Insufficient security level | 安全等级不足 | 提高应用安全等级或刷新授权安全等级 |
子错误码信息
子错误码信息 | 中文描述 | 归属方 | 解决方案 |
high-risk security breach | 存在高危安全漏洞 | ISV | 解决安全漏洞后重新发布 |
mid-risk security breach | 存在中级安全漏洞 | ISV | 解决安全漏洞后重新发布 |
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