错误处理

快速阅读

AgentSDK 的失败分两类，都要处理。

SDK 本地错误：throw 或 Promise reject，对象名是 AgentSdkError。常见原因是未初始化、参数缺失、WebSocket 未连接、超时、软电话不可用。
服务端业务失败：Promise 仍然 resolve，但 code !== 0，并带 message，有时带 errorCode。
code=0 表示成功。本文示例里失败常用 -1。

阅读地图

两类错误怎么区分：读「二」。
本地错误码：读「三」。
推荐的 async/await 写法：读「四」。
服务端 errorCode：读「五」。
方法参数见 API（操作）。

一、文档说明

本文说明座席工作台集成时如何同时处理本地异常和服务端业务失败，避免只写 try/catch 或只判断 code。

二、错误模型

SDK 本地错误（throw / Promise reject）

常见原因：参数缺失、依赖未注入、WebSocket 未连接、请求超时、软电话不可用、浏览器能力不支持。
表现形式：throw AgentSdkError / Promise.reject(AgentSdkError)。

服务端业务失败（请求已返回，但 code 非 0）

常见原因：权限不足、状态不合法、号码限制 / 风控拦截。
表现形式：操作 Promise 会 resolve，但 code !== 0，同时返回 message 和可选的 errorCode。

集成时同时处理 try/catch 和「已返回但 code !== 0」。

三、SDK 本地错误：AgentSdkError

3.1 错误对象

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

3.2 内置错误码（ErrorCodes）

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

四、推荐写法（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);
  }
}

五、服务端业务错误：errorCode

5.1 标准响应字段

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

5.2 预览外呼 errorCode

预览外呼的业务错误码与业务域、租户配置相关。集成时记录并上报 errorCode，便于排障。