错误处理

SdkError 类

SDK 统一使用 SdkError 抛出业务错误：

import { SdkError } from '@atomm-developer/generator-sdk'
// CDN: const SdkError = GeneratorSDK.SdkError

try {
  await sdk.credits.consume({ amount: 10, action: 'ai_enhance' })
} catch (err) {
  if (err instanceof SdkError) {
    console.log(err.code)    // 业务错误码（number）
    console.log(err.message) // 错误信息（string）
    console.log(err.name)    // 'SdkError'
  }
}

错误码表

code	说明	触发场景
20101	未登录 / token 无效	任何需要登录的 API 调用，SDK 自动触发退出并清除 token
40301	积分不足	credits.consume() 或 withBilling() 时余额不足
40302	action 无权限	credits.consume() 的 action 未在控制台申请
-1	网络错误 / 客户端错误	网络断开、canvas 导出失败、provider 未注册等
其他	后端返回的业务错误码	后端 { code: xxx, msg: 'xxx' } 透传

错误处理最佳实践

async function safeOperation() {
  try {
    await sdk.cloud.save({ snapshot: getState(), cover: canvas })
  } catch (err) {
    if (!(err instanceof SdkError)) throw err

    switch (err.code) {
      case 20101:
        // token 过期，SDK 已自动清除状态，引导重新登录
        await sdk.auth.login()
        break
      case 40301:
        // 积分不足
        showInsufficientCreditsDialog()
        break
      case -1:
        // 网络错误
        showNetworkErrorToast()
        break
      default:
        console.error('未知错误:', err.code, err.message)
    }
  }
}

HTTP 拦截器行为

• 请求拦截器：自动注入 uToken 和 lang Header
• 响应拦截器：
  • code === 0 → 提取 data 字段返回
  • code === 20101 → 清除 token + 触发 onTokenExpired 回调
  • 其他 code → reject SdkError(code, msg)
  • 网络错误 → reject SdkError(-1, 'Network error')
• 超时时间：60 秒