ZENAVA
Guides

错误处理

1. 错误模型概览

SDK 中的错误分为两大类：

  1. SDK 本地错误（throw / Promise reject）
  • 常见原因：参数缺失、依赖未注入、WebSocket 未连接、请求超时、软电话不可用、浏览器能力不支持等。
  • 表现形式：throw AgentSdkError / Promise.reject(AgentSdkError)
  1. 服务端业务失败（请求已返回，但 code 非 0）
  • 常见原因：权限不足、状态不合法、号码限制 / 风控拦截等。
  • 表现形式：操作 Promise 会 resolve，但 code !== 0，同时返回 message 和可选的 errorCode

强烈建议：同时处理“异常（try/catch）”和“已返回但 code !== 0”这两种情况。

2. SDK 本地错误：AgentSdkError（必须处理）

2.1 错误对象结构

  • name：恒为 AgentSdkError
  • code：错误码（字符串）
  • message：可读错误信息
  • details?：可选的额外上下文（任意类型）

2.2 内置错误码（ErrorCodes）

code含义常见触发场景推荐处理方式
NOT_INITIALIZEDSDK 未初始化在调用 setup() 之前就执行 login/previewObCall/...应用启动时先调用 setup()
INVALID_PARAMS参数非法/缺失login 缺字段、号码为空、类型错误等按文档校验参数
MISSING_DEP缺少依赖必需依赖未注入/未加载（WS/SIP 等）确认依赖已正确提供
WS_NOT_CONNECTEDWebSocket 未连接未登录或断线状态下调用依赖 WS 的操作先登录；断线后重新登录
REQUEST_TIMEOUT请求超时WS 建连超时、响应超时提示重试；记录网络质量
SIP_NOT_AVAILABLESIP/软电话不可用软电话未就绪 / UA 未准备好检查 webrtc 配置与软电话状态
MEDIA_NOT_SUPPORTED媒体能力不支持浏览器不支持 / 无权限 / 无设备更换浏览器；检查权限和设备

3. 推荐写法（async/await）

try {
  const res = await AgentSDK.previewObCall({ customerNumber: '13800138000' });

  // 服务端业务失败：Promise resolve，但 code 非 0
  if (res.code !== 0) {
    console.error('[服务端失败]', res.errorCode, res.message);
    return;
  }

  // 成功
} catch (err) {
  // SDK 本地错误（或运行时/网络错误）
  if (err && err.name === 'AgentSdkError') {
    console.error('[SDK 错误]', err.code, err.message, err.details);
  } else {
    console.error('[未知错误]', err);
  }
}

4. 服务端业务错误：errorCode（领域相关）

4.1 标准响应字段

  • code：0 表示成功；非 0 表示失败（本文档中常用 -1 表示失败）
  • message：可读失败原因
  • errorCode?：可选业务错误码（数字或字符串）

4.2 示例：预览外呼 errorCode

预览外呼的业务错误码通常与业务域/租户配置相关。集成阶段建议对 errorCode 做好日志记录与上报，便于排障和售后支持。