This page is translated by Google Cloud Translation API

Switch to Chinese

uni error specification

background

Most of the error messages of the MiniApp platform are returned in the format of errCode and errMsg. However, different MiniApp platforms may return different errCode.

In actual development, the uni-app engine, third-party plug-ins, and the developer's own business code will all return errors, but errCode may also conflict with each other.

In unified error interception and uni statistics, confusing errCode will cause many problems.

Many errors are caused by lower-level errors, but only the outermost errors are exposed, which is difficult to troubleshoot, and lower-level errors need to be exposed.

In order to further standardize the error message format, uni-app defines a more complete error specification:

1. Added errSubject, which is used to distinguish between different platforms or different modules with the same errCode
2. Added cause, which is used to feed back the source of the error. For example, on the app platform, when the uni.login API returns an error, it may be that the underlying third-party social login sdk reported an error, and the error of the third-party sdk will be added to the cause.

From 2022-11-11, all new APIs added by DCloud will use this set of uni error specifications. At the same time, we recommend that all plugin authors also use this specification and declare their own plugin id in errSubject.

define

All asynchronous APIs should return errors through the callback callback, and the error information should be included in the callback function parameters, and the callback function parameters should be of type UniError

The full error types are defined as follows:

// source error message
interface SourceError {
    message: string,
    subject?: string,
    code?: number,
    cause?: SourceError | UniAggregateError
}

//Uni聚合源错误信息
interface UniAggregateError extends SourceError {
	errors: Array<SourceError|UniAggregateError>
}

//uni error message
interface UniError {
	errSubject: string,
	errCode: number,
	errMsg: string,
	data?: Object,
	cause?: SourceError | UniAggregateError
}

//Callback
function CallBack(err:UniError){
	//console.log(JSON.stringify(res));
}

SourceError

Used to save the source error that caused the error, such as the error information of the third-party SDK on the app side, including the following attributes:

• subject
  Incorrect source (such as the third-party SDK on the app side) module name, such as the module name of the pangolin advertising SDK in uni-AD is "csj"
• code
  The original error code of the source error (such as the third-party SDK on the app side)
• message
  The original error description information of the source error (such as the third-party SDK on the app side)
• cause
  Superior source error, if there is only one source error, it will be SourceError, if it contains multiple source errors, it will be encapsulated into AggregateError

Notice
The source error can be expanded to other attributes according to the business situation. For example, in uni-AD, slotId can be added to indicate the aggregated three-party advertising slot identifier

UniAggregateError

用于保存多个源错误，如app端某个错误可能是由多个三方SDK的错误引起，可将多个源错误组成UniAggregateError对象。 Includes the following properties:

• errors
  数组，可包含SourceError或UniAggregateError对象

UniError

Uni unified error information, used to unify the error information of each platform (terminal)

• errSubject 统一错误主题（模块）名称，字符串类型，存在多级模块时使用"::"分割，即"模块名称::二级模块名称"，参考errSubject（模块/主题）名称
• errCode
  统一错误码，数字类型，通常0表示成功，其它为错误码。
  对于已经实现的API，继续保留现有errCode规范（保留向下兼容）。
  错误码长度及规范参考微信小程序的Errno错误码，使用 7 位数错误码，第 1 - 2 位标识 API 接口的一级类目，第 3 - 4 位标识 API 接口的二级类目，第 5 - 7 位表示具体的错误类型。 其他平台，与微信小程序相同的错误，错误码应尽量保持一致。定义平台专有错误码时，为了避免冲突，错误码的第 5 - 7 位按以下规则：
  • App-Android端：使用7xx
  • App-iOS端：使用8xx
  • Web端：使用9xx
• errMsg
  Unified error description information, string type, should accurately describe the cause of the error
• data
  Optional, the data returned when an error occurs. For example, when obtaining device information, if part of the data is successfully obtained and part of the data fails to obtain, an error callback is triggered at this time, and the successfully obtained data needs to be placed in the data attribute
• cause
  Optional, source error information, can contain multiple errors, see SourceError for details

When there are multiple source errors, SourceError needs to be encapsulated into an AggregateError object, and the SourceError array can be obtained as follows:

function CallBack(err:UniError){
	var cerrs:SourceError[] = err.cause.errors;
}

errSubject（模块/主题）名称

The errSubject attribute value indicates the name of the calling module that returned the error.

Module Name	Description
uni-runtime	App side SDK runtime environment error
uni-ad	uni-AD
uni-push	UniPush
uni-login	OAuth (login authentication)
uni-verify	One-key login

Notice

• The errSubject attribute value of the uni built-in module is "uni-module English name". If the English name consists of multiple words, the word key should be separated by -
• errSubject attribute value of uni API
  • uni.XXX API time The errSubject attribute value is "uni-API name", such as uni.getSystemInfo(), and the errSubject attribute value in the error callback is "uni-getSystemInfo"
  • Object.XX API time The errSubject attribute value is "uni-Object name-API name", such as SocketTask.onMessage(), and the errSubject attribute value in the error callback is "uni-SocketTask-onMessage"
• When an error is returned in the uni plugin, it is recommended to use the "plugin id" as the errSubject attribute value. If there are many APIs in the plugin, each API can be defined separately. The errSubject attribute value format is "plugin id-API name".

uts插件或uvue页面中使用UniError

在uni-app、uni-app x中的错误信息建议统一使用UniError对象，以便在发生错误时统一捕获处理，特别是以下情况：

• 在uts插件中封装API给uni-app使用时，返回的错误信息要求使用UniError对象。
• 在uni-app x项目的uvue页面中，抛出错误要求使用UniError对象。

在App端，UniError和SourceError都是从uts的Error继承。

构造UniError对象

UniError对象必须通过 new 操作符构造

语法

new UniError()
new UniError(errSubject:string, errCode:number, errMsg:string)

参数

• errSubject
  统一错误主题（模块）名称，字符串类型，存在多级模块时使用"::"分割，即"模块名称::二级模块名称"，参考errSubject（模块/主题）名称
• errCode
  统一错误码，数字类型，通常0表示成功，其它为错误码
• errMsg
  统一错误描述信息，字符串类型，应准确描述引起的错误原因

示例

//创建一个UniError  
let error = new UniError("uni-apidName", 60000, "Custom uni error");
//设置data数据（可选）  
error.data = {
	"dataName": "custom data value"
};

构造SourceError对象

当错误信息是有三方SDK或其它模块引起时，可以将三方SDK或其它模块的错误信息封装在SourceError中作为UniError的源错误

语法

new SourceError()
new SourceError(message:string)

参数

• message
  源错误描述信息，字符串类型

示例

//创建一个SourceError  
let sourceError = new SourceError("Third SDK error message");
//创建一个UniError  
let error = new UniError("uni-apidName", 60000, "Custom uni error");
//设置源错误  
error.cause = sourceError;

构造UniAggregateError对象

当错误是由多个SourceError源错误引起时，可以将多个源错误放到一个UniAggregateError对象中

语法

new UniAggregateError(errors:Array<SourceError>)  

参数

• errors
  源错误数组，Array类型

示例

//创建UniAggregateError  
let aggregateError = new UniAggregateError([new SourceError("First 3rd SDK error message"), new SourceError("Second 3rd SDK error message")]);
//创建一个UniError  
let error = new UniError("uni-apidName", 60000, "Custom uni error");
//设置源错误  
error.cause = aggregateError;