07-Error-Handling

1. Error model overview

The SDK has two categories of errors:

SDK local errors (throw / Promise reject)

Typical causes: missing parameters, missing dependencies, WebSocket not connected, request timeout, softphone unavailable, unsupported browser capabilities, etc.
Form: throw AgentSdkError / Promise.reject(AgentSdkError)

Server-side business failures (response returned but code is non-zero)

Typical causes: permission denied, invalid state, number restrictions / risk control, etc.
Form: operation Promise resolves, but code !== 0, with message and optional errorCode

Strong recommendation: always handle both “exceptions (try/catch)” and “resolved response with code !== 0”.

2. SDK local error: AgentSdkError (must handle)

2.1 Error object shape

name: always AgentSdkError
code: error code (string)
message: readable message
details?: optional extra context (any type)

2.2 Built-in error codes (ErrorCodes)

code	Meaning	Typical triggers	Recommended handling
NOT_INITIALIZED	SDK not initialized	Calling `login/previewObCall/...` before `setup()`	Call `setup()` at app startup
INVALID_PARAMS	Invalid/missing params	Missing fields in `login`, empty number, wrong types	Validate parameters per doc
MISSING_DEP	Missing dependency	Required dependency not injected/loaded (WS/SIP/etc.)	Ensure dependencies are provided
WS_NOT_CONNECTED	WebSocket not connected	Calling WS-required ops when not logged in / disconnected	Login first; re-login after disconnect
REQUEST_TIMEOUT	Request timed out	WS connect timeout, response timeout	Prompt retry; record network quality
SIP_NOT_AVAILABLE	SIP/softphone not available	Softphone not ready / UA not prepared	Check `webrtc` flag and softphone status
MEDIA_NOT_SUPPORTED	Media not supported	Unsupported browser / no permission / no device	Switch browser; check permissions/devices

3. Recommended pattern (async/await)

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

  // Server business failure: Promise resolves but code is non-zero
  if (res.code !== 0) {
    console.error('[server failed]', res.errorCode, res.message);
    return;
  }

  // success
} catch (err) {
  // SDK local error (or runtime/network error)
  if (err && err.name === 'AgentSdkError') {
    console.error('[sdk error]', err.code, err.message, err.details);
  } else {
    console.error('[unknown error]', err);
  }
}

4. Server business error: errorCode (domain-specific)

4.1 Standard response fields

code: 0 success; non-zero failure (this doc commonly uses -1 as failure)
message: readable failure reason
errorCode?: optional business error code (number or string)

4.2 Example: preview outbound `errorCode`

Preview outbound business error codes are domain/tenant dependent. During integration, it is recommended to log/report errorCode for troubleshooting and post-sales support.

Updated 4 days ago