# Errno错误码

在使用部分小程序 API / 组件时,抛出的异常(fail 回调 / Promise reject)Error 对象中除了带有 errMsg,还会带有通用错误码 errno

代码示例

wx.openBluetoothAdapter({
  success (res) {
    console.log(res)
  }
  fail (err) {
    console.log(err.errno)
  }
})

# 背景介绍

errno 错误码的出现是为了解决以下问题:

  • 目前部分 API 在出现错误时,只返回错误信息 errMsg,没有错误码。另一部分 API 虽然有 errCode,但没有形成统一格式规范。
  • 目前有 errCode 的 API 中,不同的 API 失败时返回的 errCode 粒度不同。部分 API 的 errCode 粒度太大,信息不足。
  • 相同的错误在不同的 API 中 errCode 未对齐,不便于开发者记忆和处理。

因此,我们设计了一套拥有统一规范的错误码errno,以帮助开发者更好地开发调试及处理错误。

errno 错误码有如下优点:

  • 在错误码格式上,拥有统一的设计规范。
  • 不同的 API 中出现的相同错误,对应的错误码一致。
  • 错误码中包含 API 类别信息,帮助开发者快速定位问题。
  • 不同 API 中的错误码粒度较为统一。

Error 对象中同时有 errno 错误码和 errCode 错误码时,一般以 errno 错误码为准
后续 errno 错误码会逐步推广到所有 API 接口,并取代现有的 errCode 参数,为开发者提供错误信息。

# 错误码设计

errno 错误码一般为 7 位数,第 1 - 2 位标识 API 接口的一级类目,第 3 - 4 位标识 API 接口的二级类目,第 5 - 7 位表示具体的错误类型。
例如: errno 错误码为 1504003 时,15 表示 API 接口的一级类目为 设备,04 表示 API 接口的二级类目为 NFC,003 表示具体的错误类型。
目前已接入 errno 的 API 接口涉及的类目包括:

  • 一级类目:00 - 通用错误码
  • 一级类目:01 - 基础
    • 二级类目:00 - 通用基础错误
    • 二级类目:02 - 系统
  • 一级类目:06 - 网络
    • 二级类目:00 - 通用网络错误
    • 二级类目:02 - 发起请求
  • 一级类目:15 - 设备
    • 二级类目:00 - 通用设备错误
    • 二级类目:04 - NFC
    • 二级类目:09 - 低功耗蓝牙
    • 二级类目:10 - 蓝牙

一级类目与二级类目名称 和 API 接口文档的类目名称基本保持一致。

# 最佳实践

以 API 接口 openBluetoothAdapter 为例,当蓝牙适配器不可用时,针对 openBluetoothAdapter 接口抛出的异常 Error 对象:

"err":
{
	"errMsg": "openBluetoothAdapter:fail:not available",
	"errCode": 10001,
	"errno": 1500102
}

可以通过以下代码进行异常处理:

wx.openBluetoothAdapter({
  success (res) {
    console.log(res)
  },
  fail (err) {
    // 微信无法使用蓝牙,可引导用户在系统设置中启用蓝牙
    if ( err.errno === 1500102 ) {
        wx.showModal({
            content: '微信无法使用蓝牙,请到系统设置中启用'
        })
    }
  }
})

# 错误码列表

以下是 errno 值的一览表。

errno errMsg 含义
0 ok 成功
1 cancel 撤销
3 system permission denied 系统权限未授予微信
4 internal error 小程序框架内部异常
5 time out 接口超时
100 jsapi not supported JsApi不支持
101 jsapi invalid request data JsApi请求参数非法
102 jsapi has no permission JsApi没有权限
103 jsapi user authorize denied JsApi用户拒绝授权
104 jsapi user authorize canceled JsApi用户取消授权
106 invalid jsapi index JsApi权限位序号非法
1000 server system error 服务端系统错误
1001 invalid request parameter 基础库wx接口请求参数非法
1002 empty request 空的请求
1003 meet server frequency limit 命中服务端频率限制
1004 invalid openid 不合法的openid
1005 invalid appid 不合法的appid
1006 insert data failed 添加数据失败
1007 get no data 数据不存在
1008 update data failed 更新数据失败
1009 data expired 数据过期
1010 data deleted 数据被删除
1011 invalid user id 不合法的用户身份
1012 api need post method api要求post请求
1013 api need get method api要求get请求
1014 invalid user ticket 无效的凭证
1015 invalid api 无效的接口
1016 no websocket conn info 无websocket连接信息
1017 mem err 服务端内存相关错误
1018 duplicated uuid uuid冲突
1019 not friend 不是好友关系
1020 code already used code已经使用
1021 code expired code过期
1022 invalid json json数据解析错误
1023 invalid state 无效的状态
102101 settings page not found openSystemSettings找不到对应的系统设置页
602002 request server http error http请求httpdns服务商错误
602101 not buy httpdns service 小程序未在服务市场购买httpdns服务
602102 service expired 小程序在httpdns服务市场资源包过期
602103 no enough httpdns quota 小程序在httpdns服务市场额度不足
602104 empty servicer return httpdns服务商返回结果为空
602105 time-out when request servicer 调用httpdns服务商结果超时
602106 invalid servicer response httpdns服务商返回数据不合法
602107 empty domain httpdns result httpdns域名解析结果为空
602108 not valid service id 不支持的httpdns服务商id
1500101 not init 未初始化蓝牙适配器
1500102 当前蓝牙适配器不可用
1500103 当前BLE设备获取不到Service/获取不到对应UUID的Service
1500104 调用系统蓝牙能力失败, 详细错误见errMsg
1500105 system not support 系统不支持BLE
1504001 系统不支持NFC
1504002 not support HCE 系统不支持HCE
1504003 system NFC switch not opened 系统NFC开关未打开
1504100 not set default NFC application 未设置NFC默认应用
1504101 register aids failed HCE注册aid列表失败
1504200 user is not authorized 用户未授权App使用NFC能力
1504201 parse NdefMessage failed 解析NdefMessage失败
1504202 NFC discovery already started 之前已经调用了startDiscovery
1504203 NFC discovery has not started 之前没有调用startDiscovery
1504204 Tech already connected 当前tech已经连接上
1504205 Tech has not connected 当前tech还没连接上
1504206 NFC tag has not been discovered 系统未发现NFC标签
1504207 invalid tech 无效的tech
1504208 unavailable tech 当前NFC标签不支持该tech
1504209 function not support 不支持该NFC能力
1504210 system internal error 调用系统NFC能力失败, 详细错误见errMsg
1509001 连接BLE设备失败
1509002 当前Service获取不到Characteristic/获取不到对应UUID的Characteristic
1509003 未连接上该BLE设备
1509004 当前Characteristic不支持该属性,详细错误见errMsg
1509005 BLE操作超时
1509006 device not found 未找到设备
1509007 already connect 当前BLE设备已经连接上
1509008 location permission is denied Android6.0以上, BLE扫描需授权地理位置
1509010 wait for bluetooth state change timeout iOS上调用openBluetoothAdapter后客户端等待状态更新超时
1510101 need pin 配对当前蓝牙设备需要pin码
1510102 reach max bluetooth background count 支持蓝牙后台通信的设备数目已经达到上限