For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/js-api/common-errors.md.

通用错误处理

错误返回

JS API 调用失败时,异步 API 会 reject、同步 API 会 throw 一个错误对象,其结构如下:

{
  "errNo": 1600004,
  "errMsg": "key is empty"
}
字段类型说明
errNonumber错误码。建议优先使用该字段判断失败原因。
errMsgstring错误信息,用于辅助排查问题,不建议依赖文案进行逻辑判断。

通用错误码

以下错误码由多个 JS API 共用。每个 API 实际可能返回的错误码以对应 API 页面的错误码表为准。

errNoerrMsg说明
100unknown error未知错误
102internal error内部错误
103feature not support当前环境不支持该能力
104invalid parameter参数不合法
105authentication fail身份认证失败
106system permission denied系统权限未授予
107user permission denied用户未授权
110API call prohibitedAPI 调用被禁止
112invalid result返回结果无效
113bridge unavailableJS API 暂不可用
114operation cancelled操作已取消
115operation timeout操作超时
116resource not found资源不存在
117not implemented能力尚未实现
118already exists资源已存在
120too many requests请求过于频繁

处理示例

try {
  await someJsApi();
} catch (error) {
  const { errNo, errMsg } = error as { errNo?: number; errMsg?: string };

  if (errNo === 115) {
    console.warn('操作超时,请稍后重试');
    return;
  }

  console.error(`调用失败:${errNo ?? 'unknown'} ${errMsg ?? ''}`);
}

请使用 errNo 进行程序判断,并为未识别的错误码提供兜底处理。errMsg 适合展示或排查问题,不应作为稳定的判断条件。