# 通用错误处理

## 错误返回

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

```json
{
  "errNo": 1600004,
  "errMsg": "key is empty"
}
```

<table>
<thead>
<tr><th>字段</th><th>类型</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>errNo</code></td><td><code>number</code></td><td>错误码。建议优先使用该字段判断失败原因。</td></tr>
<tr><td><code>errMsg</code></td><td><code>string</code></td><td>错误信息，用于辅助排查问题，不建议依赖文案进行逻辑判断。</td></tr>
</tbody>
</table>

## 通用错误码

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

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

## 处理示例

```typescript
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` 适合展示或排查问题，不应作为稳定的判断条件。