Error handling

BridgeError shape

All API errors use a single error format:

interface BridgeError {
  code: number      // 错误码
  message: string   // 错误描述
  data?: unknown    // 附加数据（可选）
}

Error code layout

Error codes follow a five-digit convention:

Range	Category	Description
1xxxx	Protocol / routing	Bridge protocol-level errors
2xxxx	Permission / auth	User authorization or authentication
4xxxx	Client	Invalid parameters, unsupported operations, etc.
5xxxx	Internal	System-internal exceptions

Full error code table

enum BridgeErrorCode {
  // ── 协议错误 ──
  UnhandledApi     = 10001,  // API 未注册
  InvalidRequest   = 10002,  // 请求 ID 缺失或格式错误
  ProtocolMismatch = 10003,  // 协议版本不匹配

  // ── 超时 ──
  Timeout          = 40800,  // 请求超时（等待响应）
  TimeoutAfterAck  = 40801,  // ACK 后超时（用户交互超时）

  // ── 权限/认证 ──
  PermissionDenied = 20001,  // 用户拒绝权限
  AuthFailed       = 20002,  // 认证失败（凭证无效/过期）
  BiometricCancelled = 20003, // 用户取消生物识别

  // ── 客户端错误 ──
  InvalidParam     = 40001,  // 参数缺失或无效
  NotSupported     = 40002,  // 当前环境不支持该功能
  UserCancelled    = 40003,  // 用户取消操作
  NetworkUnavailable = 40004, // 网络不可用

  // ── 内部错误 ──
  InternalError    = 50000,  // 未知内部错误
  BridgeDestroyed  = 50900,  // Bridge 已销毁
}

Catching errors

try/catch

import woo from 'mini-sdk'
import { BridgeErrorCode } from 'mini-sdk'

try {
  const result = await woo.getLocation()
  console.log('位置：', result)
} catch (err) {
  switch (err.code) {
    case BridgeErrorCode.PermissionDenied:
      woo.showToast({ title: '请授权位置权限', icon: 'none' })
      break
    case BridgeErrorCode.Timeout:
      woo.showToast({ title: '请求超时，请重试', icon: 'none' })
      break
    case BridgeErrorCode.NotSupported:
      woo.showToast({ title: '当前环境不支持此功能', icon: 'none' })
      break
    default:
      woo.showToast({ title: err.message, icon: 'none' })
  }
}

Callback style

woo.getLocation({
  success(result) {
    console.log('位置：', result)
  },
  fail(err) {
    console.error(`错误 [${err.code}]: ${err.message}`)
  },
  complete() {
    console.log('调用完成')
  },
})

Global error handling

Register a catch-all handler with setErrorHandler:

import { setErrorHandler } from 'mini-sdk'

setErrorHandler((message) => {
  // 所有未被业务代码 catch 的错误都会进入这里
  console.error('[全局错误]', message)
  woo.showToast({ title: message, icon: 'none', duration: 3000 })
})

Default behavior

On SDK init (woo.hello()), a default error handler is registered and uncaught errors are shown with Toast. You can override this with setErrorHandler.

Timeouts

Bridge has two levels of timeout:

Stage	Default	Description
Request	10s	Timeout while waiting for a host response
After ACK	5 min	After the host sends ack, for user-interaction flows

Interactive flows (e.g. showDialog, showActionSheet) use timeout = 0 (no automatic timeout):

// showDialog 内部实现
bridge.call('UI', 'showDialog', payload, 0)
//                                       ^ timeout = 0，等待用户点击

ACK flow

SDK                         Host
 │ ── req ──────────────────► │
 │                            │ Request received; user action required
 │ ◄─── ack ─────────────────│ "Received, processing"
 │                            │  ← timeout reset to 5 min
 │   ... user interaction ... │
 │ ◄─── res ─────────────────│ Return result

getErrorMessage helper

import { getErrorMessage } from 'mini-sdk'

try {
  await woo.someApi()
} catch (err) {
  const message = getErrorMessage(err)
  // 统一转换为可读字符串
}