API异常排查方法


一、快速排查问题

1、快速排查问题流程图

TB1k0YFFVXXXXbFXpXXSutbFXXX.jpg

 

附：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、排查问题详细流程图

详细描述开发者发现以上问题之后的处理流程。

T1jOVMXbxCXXaMCXbX.jpg

 

3、快速排查问题范例

范例1

我从错误日志中分析出来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级别授权

ISV

进行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、其它特有错误码

QQ截图20170213173848.png

 

 

 

 

FAQ

  • 关于此文档暂时还没有FAQ