一、异常排查

1. 请求流程

一个完整的奇门请求可以简单总结为如图：

一个请求经过的节点较多，为了简化起见，我们把错误原因归纳为以下三类：

1）客户端错误（请求发起方）；

2）奇门错误（请求转发网关）；

3）服务端错误（请求接收方）。

2. 错误查看方式

一个典型错误应答报文包含四个关键字段：flag、code、message、top_reuqest_id，如果是非仓储API还包含字段sub_code和sub_message。其中flag字段为failure表明这是一个错误应答，code字段表明这个错误是哪一方的错误，message字段是错误的详细描述，可以根据这个字段的内容去文档中查询解决方案，top_reuqest_id字段用于在奇门日志查询中查询这一个请求的详细信息。下面是典型的错误应答：

奇门仓储API

<response> 
  <flag>failure</flag>  
  <code>TOP60</code>  
  <message>qimen internal error | qimen.request-convert-error | Signature is invalid, customerId is xxx, fromAppkey is xxx, original signature is 326DF300F2BFBD7BFBB930DA22520</message>  
  <top_reuqest_id>3vpdvzd2gux</top_reuqest_id> 
</response>

普通API

{
    "response": {
        "flag": "failure", 
        "code": 15, 
        "message": "Remote service error", 
        "sub_code": "isp.http-connection-timeout", 
        "request_id": "4afs8rmwh25"
    }
}

3. 判断错误来源

一般错误原因可以根据如下方式来判断，在确定了初步原因后可以根据后文的对应问题来解决。

1. 客户端错误一般有两种情况：

1.1 本地异常，此时请求还未到达奇门，比较常见的是网络异常，比如抛了java.net.SocketTimeoutException。

1.2 参数错误，比如路由参数错误，此时奇门会返回错误码为TOP60，详细错误在message字段有描述。

2. 奇门内部错误情况如下，可以联系小二处理

2.1 返回值为TOP1，此时联系奇门小二解决问题。

2.2 奇门返回的http状态码不等于200。

3. 服务端错误需要区分为两种：

3.1业务错误，此时错误码一般为服务商自己定义，一般返回的错误码中不会包含TOP1、TOP60、TOP15或其他TOP后跟数字的字符串，如果看到此类的错误应该优先找服务提供方来排查问题。

3.2 系统错误，此时返回错误码会包含TOP15，message会包含Remote service error的提示，如果看到此类的错误应该优先找服务提供方来排查服务器状态或接口是否正常。

4. 客户端错误

1）参数错误

参数错误会返回code为TOP60的错误码或者其他TOP错误码，并返回具体错误的字段，比如：

<xml version="1.0" encoding="utf-8" >
<response><flag>failure</flag><code>TOP60</code><message>qimen internal error:Standard request parse error \ orders/order/aaa</message>
</response>

此时调用方可以根据message中提示的错误的字段（例如上面的orders/order/aaa）结合API的定义文档来排查解决。

其他错误可以根据message字段中的值在下表中搜索解决方案。

错误示例	原因&排查
failure TOP60 qimen internal error \ qimen.request-convert-error \ Signature is invalid, customerId is xxx, fromAppkey is xxx, original signature is 326DF300F2BFBD7BFBB930DA22520 3vpdvzd2gux	签名问题的排查思路： 1.TOP60的报错，且报错code和message和左侧信息一致，那么是奇门校验不通过，其他的code为联调对方返回的报错，联系对方解决。 2.如果使用的是SDK方式，请先检查secret和appkey是否是对应，在应用管理的概览页面查看 3.如果不用SDK，直接调用API的方式，很容易出现签名的错误，可能存在的原因如下： 1）确保参数已经排序，要求是url里面有的参数都必须参与签名（sign除外）。 2）拼接body，不需要对body做任何处理。 3）前后拼接secret，注意secret一定要和appkey对应，日常环境用沙箱appkey，线上环境用正式appkey。 4）时间戳的问题，使用最原始的时间戳进行签名，也就是encode之前的。 5）确保参与签名的时间戳和发给奇门的http请求中URL里的时间戳是同一个。 6）完成以上步骤后，计算签名，可以找个在线md5计算的网址计算一下，对比一下你的签名和网上的签名，确保签名是32位的。 7）如果和网上签名一致，但是发到奇门还是报错，有以下几种可能：   a）奇门没有收到body数据，要求是body使用http post payload发送，而且要注意不能是表单提交，http header里面的Content-Type=application/x-www-form-urlencoded默认是form表单提交，改成Content-Type=application/xml; charset=utf-8，而奇门是从post流里面读数据。   b）奇门收到的body有中文乱码。   c）secret使用错误，奇门会根据appkey去获取对应的secret，所以ISV在签名的时候务必使用正确的secret。 8）ITC提供了签名工具，可以用工具再试一下。 9）验证签名的时候，不要替换url里面的appkey，收到的url里面的appkey是什么就用什么，不要改动url和body，否则会签名失败。 10）把计算md5之前拼接好的字符串打出来，和url、body做一下对比，看看参数是不是一致的。 11）接收报文的时候建议用字节来读，不要按行读，不然会导致验证签名失败。 综上，强烈建议使用SDK规避该问题。
failure TOP60 qimen internal error\ qimen.request-convert-error\ Failed to get seller information ? 4lyarv7rrksb	1.请求URL中customerId参数没传 2.customerId拼写错误(例如customerid) 3.请求URL中包含换行符等非法字符,将customerId截断了
failure TOP60 qimen internal error \ qimen.request-convert-error \ [QIMEN-ERROR] 获取不到卖家[tuserid=null, customerId=888888888, app_key=11111]的授权关系 6jxv72ailnp failure TOP60 qimen internal error \ isp.route-error\路由服务信息异常 6ni1royd4a9 failure TOP68 qimen route error no-route-error The specified route could not be found 4drfw84bj0bk	授权关系错误，要么是参数用错，要么是奇门没有配置： 1.检查app_key和customerId是否配对。 2.app_key没传，拼写错误（如：appkey），值为空（如：app_key=&customerId=c1234567890）。 3.检查接入奇门的环境(测试：https://qimen.api.taobao.com/top/router/qmtest ，线上：http://qimen.api.taobao.com/router/qimen/service ） 4.确定参数配置的是否正确，在控制台里的奇门中心，查看线上或者测试环境的配置。 5.如果以上检查都没问题，请联系小二处理
failure TOP60 qimen internal error \ qimen.request-convert-error \ Cannot get destination appkey, unresolvable url=…. ? 10c0v2l0f8u5	1.请求URL中method没传 2.method拼写错误,注意大小写（比如methed） 3.method参数值错误(拼写错误,有空格，或者是没有加上taobao.qimen.等) 4.在控制台确认appkey是否存在，如果是沙箱环境请使用沙箱的appkey，正式环境一样
fill-qimen-topRequest-error	请检查API名是否合法，API名必须是完整的，比如taobao.qimen.transferorder.query不能缩写成.transferorder.query
failure TOP60 qimen internal error:Standard request parse error \ orders/order//aaa	请求body出错，可能的原因如下： 1.XML开始节点与结束节点不匹配，例如 商品数量应该小于100.个 ，或者没有结束节点 2.XML节点中包含空格，例如< remark>商品数量应该小于100个；或者 商品数量应该小于100个</ remark>；或者 商品数量应该小于100个< /remark> 3.XML节点的值包含“<”字符，例如 商品数量应该<100个 ，解决方法： <![CDATA[商品数量应该<100个]]> 4.XML节点与标准请求中节点名不匹配，例如 商品数量应该小于100个 5.XML节点缺失，例如标准请求 ，开发人员写成了 6.XML节点重复，如 ，错误信息为remark[2] 7.请求body体为空，错误信息为input contained no data、null 8.接口与报文不匹配 9.检查url中的版本号v，现在是2.0(测试挡板会校验版本号) 10.XML中包含除< > & &qout; ’之外的&other;特殊字符串，这些都不符合xml规范。 11.节点位置错误，比如在entryOrder节点下的，放到了request下面。 12.Could not instantiate converter : com.thoughtworks.xstream.converters.extended.DurationConverter : null，这个错误是由于奇门系统在启动时需要加载一个模块，遇到这种错误，重试即可，一般很少会碰到。
<xml version=“1.0” encoding=“utf-8” > failure TOP60 qimen internal error:Standard request parse error \ get apiDefine from TOP error	如果是商品通接口，请联系小二处理，其他接口请确认下接口名是否正确和完整
<xml version=“1.0” encoding=“utf-8” > failure TOP7 App Call Limited accesscontrol.limited-by-app-access-count 访问受限，排查api/App/权重流控；This ban will last for 43472 more seconds 10u9bstse02zb	app流控，奇门一般情况下没有流控的，但是appkey本身有流控，规则跟开放平台一致；可以到https://work.open.taobao.com 对应的应用管理下，查看“证书流量”，点击“重置流量控制”自助恢复；如果您评估日流量不够使用的话，可以点击“流量自助申请”来扩大日流量包
{“response”:{“flag”:“failure”,“code”:7,“message”:“App Call Limited”,“sub_code”:“accesscontrol.limited-by-dynamic-access-count”,“sub_message”:“This ban will last for 58 more seconds”,“request_id”:“8dq638mipivr”}}	动态流控，一般情况下是服务提供方配置了流控，可以咨询服务提供方是否配置了流控造成的。

2）网络异常

这种情况一般是客户端到奇门中间的网络链路存在问题，请求一般还未到达奇门，在中间的网络上就断了；

① Connection time out

请检查网络带宽是否正常，检查出口带宽或者网卡是否打满，如果带宽没问题，则继续往下排查。

确定网络链路是否存在问题。

2.1 从应用机器上尝试多次访问域名，看下是否存在连接超时的情况。

for i in `seq 200`;do time curl -I -w %{time_namelookup}::%{time_connect}::%{time_starttransfer}::%{time_total}::% http://qimen.api.taobao.com/router/qimen/service;done

2.2 多试几次如果不存在网络问题的话则检查下是否是应用逻辑的问题，比如请求的地址有误，如果请求存在问题，则往下继续排查

使用ping确定网络是否丢包，traceroute 或者mtr定位网络丢包节点，可以参考该文档来排查；
如果确定了丢包情况存在并确定是运营商丢包，可以截图并反馈给运营商处理；线上紧急恢复可以联系小二帮忙处理。

② Connection refuse

一般情况下奇门是不会拒绝连接的，可很可能是请求的ip地址有误造成的。

i）确定是否配置了host，如果配置了host，可去除后再测试；

ii）使用nslookup命令查看域名解析过程，并跟小二确认地址是否正确。

5. 奇门错误

线上服务如果没有变更突然出现成功率下跌，则判断是否以下状况：

1）奇门返回状态码为1，并且Message为Platform System error且无其他信息；

2）请求完整并且返回的http状态码非200，比如302或者500等，比如下面返回：

<html><body><h1>503 Service Unavailable</h1>
No server is available to handle this request.
</body></html>

如果出现如上的现象可以把问题反馈给小二，让小二协助排查。

6. 服务端错误

1）业务错误

仓储API的错误码没有包含TOP关键字，即使提示某个参数错误也并非奇门返回的，这种错误需要联系对端服务方（例如菜鸟同学）解决，比如：

<response>
 <flag>failure</flag>
 <code>S01</code>
 <message>customerid参数错误</message>
</response>

如果是普通奇门API则code为15，此时sub_code和sub_message为服务端返回，比如：

{
"response": {
    "flag": "failure", 
    "code": 15, 
    "message": "Remote service error", 
    "sub_code": "1111", 
    "sub_message": "{"message":"参数错误"}", 
    "request_id": "evygmhylstl"
}
}

对于这种错误优先找服务提供方，让服务提供方查找对应的日志，如果服务提供方反馈没有收到请求，则在联系小二协助排查。

2）系统错误

后端服务异常问题，这种错误码为TOP15,message为Remote service error | isp.xx比如：

仓储API

<response>
    <flag>failure</flag>
    <code>TOP15</code>
    <message>Remote service error | isp.http-connection-refuse</message>
    <top_reuqest_id>3nsp2abxdzu</top_reuqest_id>
</response>

普通API

{
    "response": {
        "flag": "failure", 
        "code": 15, 
        "message": "Remote service error", 
        "sub_code": "isp.http-connection-timeout", 
        "request_id": "4afs8rmwh25"
    }
}

这种需要服务方来排查，可以根据以下错误原因来排查：

message	原因&解决
isp.http-connection-refuse	1）连接拒绝：服务提供方系统挂了或者负载过高 2）服务提供方配置了Ip白名单，需要把开放平台的访问地址配置到白名单中
isp.http-read-timeout	服务提供方接受到请求，但处理时间超过了api的配置处理时间上限(不同API的配置时间不同）。可以让服务提供方查询服务日子看实际处理时间；如果是批量接口可以降低每次请求量再试试
isp.http-connection-timeout	连接超时：服务提供方网络问题（防火墙）、负载过高、网络拥塞。
isp.http-closed	连接关闭：对方系统收到请求后没有回应，并发出了关闭请求的信号
isp.http-service-unavailable	服务方返回的信息非api规定的json/xml格式，这种情况经常是返回了一个失败的html页面信息，如果请求还没到达应用层，此时可以检查nginx日志，否则检查一下请求日志
isp.http-service-status-error	服务方返回状态码非200，比如404或者503，可能请求还没到达应用层，此时可以检查nginx日志

如果是刚对接或者服务提供方做了网络调整，请首先检查配置的地址是否正确，从实际情况来看配置对应不上的情况占了大多数；如果确定配置没问题，请首先检查防火墙和服务监控。

如果服务提供方使用了域名绑ip的方式来提供服务，在更换ip的时候要先确保原有的ip没有流量后在下掉，否则域名缓存未更新时候可能会请求到老的ip上，紧急情况可以把服务地址暂时先修改为ip地址处理。

二、日志排查

1. 日志查询工具

日志查询使用该地址(需要先登录控制台)来查询，请务必填写Api名称和Appkey，如果知道确定的请求，请填写具体的sign字段或者requestId，如果您使用的是奇门仓储API，可以在关键字一栏填写具体的订单号。

2. 请求打印

为了出现问题的时候能快速定位问题，请务必做前期日志打印，特别是问题日志打印。如果您使用的是SDK，只需要配置日志输出路径即可，调用出错的时候SDK会打印错误的请求，到时候可以根据请求中的sign字段来排查，如果是自己封装的请求，也请做好问题请求的打印；如果请求错误，网关会返回requestId，也可以对这个id做好记录，方便后续排查。

三、双十一问题处理

1. 仓储推单慢了推不下去

推单慢请根据以下几个步骤排查：

1） 一直都是请求异常导致推单慢，异常排查请根据上文来排查问题。

2）请求响应慢造成推单慢。

① 先从客户端日志找出请求慢的请求，然后在奇门日志查询，查看慢在哪个；

② 如果奇门日志没有慢的问题点，首先检查网络情况，确定是否存在网络延迟问题；

③ 如果存在网络延迟问题，重点检查带宽问题，大促期间可能会造成出口带宽打满的情况；

④ 如果上述问题未能解决，请联系小二处理。

2. 解决经验

根据以往经验，大促期间推单遇到的问题大部分都是由于网络问题造成，所以重点根据以上的网络问题来排查；

另一个重要原因是由于机器压力大导致处理慢，可以尝试降级，降低推单的速率，降低双方服务器的压力再观察情况是否有所好转，在推单完全无法进行的情况下，适当降级也是必要的。

3. 问题上报

当天网络问题紧急可以找对应聚石塔/阿里云同学帮忙排查，未知奇门问题可以在奇门云网关技术支持群反馈，当天必快速处理，群号 :1群：11746343（已满）、2群 : 21771580（已满）、3群：23396781。