开发异常说明更新时间:2016-04-07 

错误模型描述

对于服务开放平台来说,不管发生了什么错误,都必须返回相应的错误报文,以便客户端应用能够根据错误报文做出相应的响应。每个服务都可能存在各种错误,如服务参数 不合法、访问权限不足、版本不正确、访问超限等等。

千米开放平台的错误模型分为主错误和子错误两个层级,每个错误报文都会对应一个主错误和 若干个子错误,主错误描述错误的类型,子错误说明错误的原因。子错误根据责任归属可 以划分为 ISP(Internet Service Provider)和 ISV(Independent Software Vendors)两种类型的错 误。如下图所示:

ISP 代表平台服务提供商一方,如服务内部异常、服务端数据库资源不可用等错误,其责任归属于 ISP,这类错误称为 ISP 错误。ISP 错误的错误编码以“isp.”为前缀,如 isp.xxx-service-unavailable、isp.xxx-service-timeout 等。ISV 代表基于平台服务开发应用的开发者一方,这类错误产生的原因是由于开发者造 成的。ISV 错误的错误编码以“isv.”为前缀,如 isv.invalid-permission、 isv.missing-parameter:xxx 等。

下面是一个完整的错误报文示例:

 {
    "errorToken": "@@$-ERROR_TOKEN$-@@",
    "code": "33",
    "message": "非法的参数",
    "solution": "请查看根据服务接口对参数格式的要求",
    "subErrors": {
      "subError": [{
          "code": "isv.invalid-paramete:XXXX",
          "message": "参数XXXX无效,格式不对、非法值、越界等"
        }]
  }

error代表主错误,它拥有一个对应编码,此外还包括错误消息及解决方法。subErrors 元素中包含多个子错误,详细说明是哪些参数违反数据了校验规则,子错误的编码附带了 违反校验规则的参数名,对定位错误非常有帮助。

系统级主错误编码

千米开放平台内置定义了一套和业务无关的错误代码体系,我们称这些错误为系统级错误。主错误都对应一个唯一的数字编码,目前共包括 30 个主错误,通过下表 进行说明:

错误编码 错误说明 错误编码 错误说明
1 服务不可用 2 开发者权限不足
3 用户权限不足 4 图片上传失败
5 HTTP方法被禁止 6 编码错误
7 请求被禁止 8 服务已作废
9 业务逻辑出错 22 缺少appKey参数
23 无效的appKey参数 24 缺少签名参数
25 无效的签名 26 缺少方法名参数
27 不存在的方法名 28 缺少版本参数
29 非法的版本参数 30 不支持的版本号
31 无效的报文格式类型 32 缺少必选参数
33 非法的参数 34 用户调用服务的次数超限
35 会话调用服务的次数超限 36 应用调用服务的次数超限
37 应用调用服务的频率超限 101 缺少accessToken参数
102 该accessToken不存在或已过期 103 访问权限不足
104 该用户已被冻结 105 获取用户信息失败
106 该应用已被冻结 107 尚未通过登录策略校验
108 非法的IP访问 109 缺少timestamp参数
110 无效的timestamp参数

30 个系统级错误可以划分为以下几类:

  • 系统级参数错误:这类错误是由于系统级请求参数缺失或不合法引起的,20~31 、101、102
  • 业务级参数错误:业务级参数缺失或不合法而引起的错误,如 32 和 33;
  • 服务访问超限错误:客户端的服务调用超过配额,34~37;
  • 权限不足错误:如2和3的错误都是开发者或应用用户的权限不足,造成服务无法访问的错误;
  • 其它错误:以上类型之外的错误。

系统级子错误编码

子错误的编码是一个格式化的层级编码串,如 isp.xxx-service-unavailable、 isv.xxx-not-exist:invalid-yyy 等,其中 xxx 和 yyy 都是变量占位符,会根据具体的错误填写 相应的值。

ISP子错误编码

千米开放平台目前仅拥有两个 ISP 的子错误,它们对应的主错误编码为 1,即 Service Currently Unavailable 主错误。这两个ISP子错误分别是:

  • isp.xxx-service-unavailable=调用后端服务{0}抛异常:{1},服务不可用。\n 异常信 息:\n{2}
  • isp.xxx-service-timeout = 调用{0}服务超时,该服务的超时限制为{1}秒,请和服 务平台提供商联系
因千米开放平台原因产生的任何错误,如数据库连接不上,某个服务资源不可用,内部抛出异常等,都对应 isp.xxx-service-unavailable 的ISP子错误。其中子错误代码中的 xxx 会被替换成具体的服务名。如 user.get 服务对应的子错误码为:isp.user-get-service-unavailable。 isp.xxx-service-unavailable 的错误消息是带参数的格式化串,开放平台会将引起错误的异常 信息格式化到消息内容中。

ISV子错误编码

在实际应用中,开发者遇到更多的都会是 ISV 的错误。千米开放平台定义了5个ISV子错误, 说明如下:

  • isv.missing-parameter:xxx=缺少必要的参数{0}
  • isv.parameters-mismatch:xxx-and-yyy=传入的参数{0}和{1}不匹配;
  • isv.invalid-paramete:xxx=参数{0}无效,格式不对、非法值、越界等
  • isv.invalid-permission=权限不够、非法访问
  • isv.xxx-not-exist:invalid-yyy=根据{0}查询不到{1}
其中,前 3 个子错误都是由于业务级参数未能通过合法性校验而引起的。当请求参数为必传时,如果未提供该参数就会报出 isv.missing-parameter:xxx 子错误,其中 xxx 为具体的参数名。 开放平台将请求参数绑定到请求参数对象属性时,如果发生类型不匹配的错误(如将 aaa 赋给一个整型的属性),将返回 isv.parameters-mismatch:xxx-and-yyy 的子错误码,其中 xxx 为参数名,而 yyy 为请求参数的值。违反其它校验规则的统一返回 isv.invalid-paramete:xxx 的子错误,其中 xxx 为未通过校验的参数名。 如果用户的权限不足,不能访问某个受限平台服务,将返回 isv.invalid-permission 的子错误, isv.xxx-not-exist:invalid-yyy 子错误表示不存在对应某个 ID 的对象,如根据 userId 获取 用户对象时,如果查不到对应的对象,则返回该子错误。

业务级子错误编码

系统级子错误模型是业务无关的通用性错误,在调用千米开放平台时,一定会有很多业务相关的错误。如删除一个不允许删除的业务单据,在单据未通过审核时直接审批等等,这些业务相关的错误,称之为业务级子错误。 开放平台有一个通用的业务级子错误编码: isv.xxx-service-error:yyy,其中 xxx 为服务的方法名即接口API名称,而 yyy 为业务错误代码,一般由8位数字字符组成,来看一个具体的业务级子错误编码的示例:
  • isv.qianmi-cloudshop-items-onsale-get-service-error:01039007 表示无效的排序字段
  • isv.qianmi-cloudshop-item-get-service-error:01030001 表示查询的商品不存在
具体的错误码请参考各API接口文档异常说明,您也可以通过点击错误码自查工具,使用错误码自查工具进行异常排查。