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