错误处理

SDK 公开两类标准错误：

HbMiniProgramSDKError：SDK 初始化或开放能力调用失败。
HbMiniProgramNetworkError：网络请求已返回，但 HTTP 状态未通过 validateStatus。

import { HbMiniProgramNetworkError, HbMiniProgramSDKError, network } from '@heybox/hb-sdk'

try {
  await network.request({ url: 'https://api.example.com/data' })
} catch (error) {
  if (error instanceof HbMiniProgramNetworkError) {
    console.log(error.status, error.data, error.headers)
    return
  }

  if (error instanceof HbMiniProgramSDKError) {
    console.log(error.code, error.message, error.data)
    return
  }

  throw error
}

错误边界

结果	表示什么	常见处理
`HbMiniProgramSDKError`	握手、参数、权限、Host 能力或模块操作失败	按稳定 `code` 分支，`message` 仅用于开发者提示
`HbMiniProgramNetworkError`	`network.request()` 已获得 HTTP 响应，但状态未通过 `validateStatus`	读取 `status`、`data` 和安全响应头
`undefined` / `deleted: false` 等空结果	API 明确定义的正常结果，例如排行榜中没有当前用户记录	正常渲染空态，不进入错误上报
其他异常	业务回调、页面代码或非 SDK 依赖抛出的错误	不要伪装成 SDK 错误；保留原异常继续交给统一错误边界

HbMiniProgramNetworkError 不是“所有网络失败”的父类：只有已形成标准 HTTP 响应且状态校验失败时才使用它。握手、bridge、Host transport 或权限失败仍属于 HbMiniProgramSDKError。业务不应通过 status === 0 猜测网络错误。

HbMiniProgramSDKError.data 是按错误码提供的可选诊断信息，不保证所有 Host 版本结构一致。读取前应做类型收窄，日志上报也必须先移除 token、授权码、文件路径、请求正文和用户隐私数据。

处理原则

根据 error.code 区分运行环境、权限、超时和业务失败，不要只比对错误文案。
对未知 code 使用通用失败 UI 并保留诊断信息；不要用穷举 switch 的 default 自动重试。
权限失败时给出可理解的提示，不要将它当成未登录。
PERMISSION_NOT_IN_SNAPSHOT 表示所需权限不在当前运行实例的授权快照中。先检查本地 Manifest 声明，再重新打开调试会话获取新状态；需要平台批准的能力仍须完成审批。不要在同一实例中循环重试。旧 Host 仍可能返回 PERMISSION_NOT_DECLARED，兼容处理这两个错误码。
PERMISSION_NOT_DECLARED 表示当前版本没有在 package.json#heybox.permissions 声明所需权限，应修改项目配置并重新构建、提交版本。
PERMISSION_DENIED 表示权限已声明，但需要的平台批准缺失或批准配置不足。network、companion、workspaceCards 需要平台批准；appProtocol 权限及 device.executeProtocol() 暂不对外开放，不提供开发者申请入口，不要反复申请或重试。
RATE_LIMITED 表示上游返回 403/429，或该 endpoint 处于 Runtime 熔断窗口；error.data.status 是上游状态码，error.data.retryAfterMs（可能缺失）是建议退避时长。不要立即重试，按建议时长退避或提示用户稍后再试。
RATE_LIMITED_BY_RUNTIME 表示 Runtime 本地拒绝（每 session 配额或同一接口的循环检测），请求没有到达上游；error.data.origin 为 'budget' 或 'loop'。这通常说明调用方在循环里高频请求，应检查调用逻辑而不是加重试。
USER_GESTURE_REQUIRED 表示潜在授权 UI 缺少可信用户手势，应让用户点击按钮后重试。
AUTHORIZATION_CANCELLED 表示用户取消、拒绝或关闭授权页面，应正常结束当前操作。
SERVER_API_REQUIRED 表示无网络的 local 模式调用了 auth.login()，需要为当前版本启用有效网络权限后再获取授权码；只需本地用户资料时使用 user.getInfo()。
METHOD_FORBIDDEN 表示当前 Host 未实现或关闭对应能力。V1 files/download 在 Web、Browser Dev Host 和未实现该能力的旧版 Host 会得到该错误；Android/iOS 1.3.396+ 需先经 system.describe 协商到对应 operation 集。
ENVIRONMENT_NOT_READY 表示在 SDK 完成握手前调用了 environment.getInfoSync()；一般改用会自动等待的 environment.getInfo()。
FILE_PICKER_CANCELLED 表示用户取消了外部文件或目录选择，应正常结束当前操作。
DOWNLOAD_CANCELLED 表示取消意图先于 Host 提交生效；Host 已完成提交时仍返回成功。DOWNLOAD_TIMEOUT 表示网络空闲超时，失败不会改动原目标。
COMPANION_NOT_PREPARED 表示启动前尚未显式准备；应由新的用户操作调用 companion.prepare()，不要在 launch() 中自动重试。
COMPANION_PREPARATION_CANCELLED 表示取消意图已结束当前观察；原子提交可能已完成，应重新查询准备状态再更新 UI。
COMPANION_SESSION_OWNERSHIP_LOST 表示 Session controller 已由新的 Runtime generation 接管；停止旧 controller 写入，需要继续取得控制权时重新取得活动 Session。
COMPANION_SESSION_EXITED / COMPANION_PIPE_CLOSED 表示当前 Session 或 stdin 已进入终态；不要对同一 controller 重放写入。
COMPANION_PROCESS_CRASHED / COMPANION_OUTPUT_LIMIT 表示进程异常退出或输出越界；先展示退出状态并保存诊断，再由新的用户操作决定是否重启。
COMPANION_DESCRIPTOR_UNAVAILABLE 表示授权或描述符暂时不可用，Runtime 会保留 retryable: true。
COMPANION_INTEGRITY_FAILED、COMPANION_ARCHIVE_INVALID 或操作系统拦截都不能绕过；停止重试并修正归档后提交新审核版本。
DOWNLOAD_HTTP_STATUS 的 data 只包含脱敏后的 status、可选 statusText 和安全响应头。
超时或运行环境不可用时，允许用户重试或退出当前流程。
上报 code、message 和必要的业务上下文，不要上报用户凭据或敏感数据。

完整错误码和字段见 HbMiniProgramSDKError 与 HbMiniProgramNetworkError。

业务层建议

import hbSDK, { HbMiniProgramSDKError } from '@heybox/hb-sdk'

type LoginViewState =
  | { status: 'ready' }
  | { status: 'cancelled' }
  | { status: 'failed'; error: HbMiniProgramSDKError }

async function loginFromUserAction(): Promise<LoginViewState> {
  try {
    const result = await hbSDK.auth.login()
    await exchangeCodeWithDeveloperServer(result.code)
    return { status: 'ready' }
  } catch (error) {
    if (error instanceof HbMiniProgramSDKError) {
      if (error.code === 'AUTHORIZATION_CANCELLED') {
        return { status: 'cancelled' }
      }
      reportSDKError(error.code, error.message, error.data)
      return { status: 'failed', error }
    }

    throw error
  }
}

async function exchangeCodeWithDeveloperServer(code: string) {
  await hbSDK.network.request({
    url: 'https://api.example.com/session/heybox',
    method: 'POST',
    data: { code },
  })
}

function reportSDKError(errorCode: string, message: string, data?: unknown) {
  console.log('[hb-sdk]', errorCode, message, data)
}

授权码在取得后立即交给开发者服务端交换，不要写入页面状态、DOM、日志或持久化存储。UI 只处理服务端会话是否建立成功。

文件与下载仍使用 HbMiniProgramSDKError，不会新增第三种错误类。业务根据 error.code 处理 picker 取消、授权撤销、文件缺失、quota、下载状态或取消，不依赖 message 文案，也不要记录真实路径、内部 handle 或响应凭据头。

Companion 失败仍使用 HbMiniProgramSDKError。prepare 与 launch 的授权取消属于两次独立用户决定；业务不得在一次点击中自动串联授权，也不得用 Browser Fake 成功替代 Windows/macOS 真机错误处理验证。完整状态机见受管桌面程序。

文件上传还可能返回 UPLOAD_CANCELLED（取消）、UPLOAD_TIMEOUT（网络空闲超时）、UPLOAD_NETWORK_FAILED（传输失败）和 FILE_CHANGED（可检测的源文件变化）。这些错误不能证明服务端未保存数据；重试由调用方按业务幂等协议决定。

错误处理 ​

错误边界 ​

处理原则 ​

业务层建议 ​

错误处理

错误边界

处理原则

业务层建议