跳转到内容
Imbrace SDK

错误处理

SDK 抛出的所有错误都继承自一个公共基类，因此可以在一处捕获所有 SDK 错误，或在需要不同处理时按具体子类分支。TypeScript 和 Python SDK 的错误层级完全相同。

错误层级

Error
└── ImbraceError          （基类 — 捕获所有 SDK 错误）
    ├── AuthError          （401、403 — 无效或过期的凭证）
    ├── ApiError           （4xx/5xx — 服务器拒绝请求）
    └── NetworkError       （超时、连接被拒绝、DNS 失败）

如需查看特定错误消息和已知修复方法，参阅问题排查。

AuthError

当服务器返回 401 或 403 时抛出 — 凭证无效、过期或已被撤销。

import { AuthError } from "@imbrace/sdk";


try {
  const me = await client.platform.getMe();
} catch (e) {
  if (e instanceof AuthError) {
    console.error("需要重新认证：", e.message);
  }
}

ApiError

对所有其他 4xx 和 5xx（429/5xx 重试耗尽后）抛出。

import { ApiError } from "@imbrace/sdk";


try {
  await client.marketplace.getProduct("nonexistent_id");
} catch (e) {
  if (e instanceof ApiError) {
    console.error(`HTTP ${e.statusCode}: ${e.message}`);
    // 例如："HTTP 404: Product not found"
  }
}
属性类型说明
statusCodenumberHTTP 状态码
messagestring服务器响应中的错误消息

NetworkError

请求未能到达服务器时抛出 — 超时、DNS 失败或连接被拒绝。

import { NetworkError } from "@imbrace/sdk";


try {
  await client.platform.getMe();
} catch (e) {
  if (e instanceof NetworkError) {
    console.error("无法连接 baseUrl：", e.message);
    // 例如："Request timed out after 30000ms"
  }
}

捕获所有 SDK 错误

导入基类以在单个块中处理任何 SDK 产生的错误：

import {
  ImbraceClient,
  ImbraceError,
  AuthError,
  ApiError,
  NetworkError,
} from "@imbrace/sdk";


try {
  await client.platform.getMe();
} catch (e) {
  if (e instanceof AuthError) return handleAuthError(e);
  if (e instanceof ApiError) return handleApiError(e);
  if (e instanceof NetworkError) return handleNetworkError(e);
  if (e instanceof ImbraceError) return handleUnknown(e);
  throw e; // 重新抛出非 SDK 错误
}

自动重试行为

两个 SDK 的 HTTP transport 均以指数退避自动重试瞬时故障。重试次数在不同语言间略有差异，但条件相同。

条件行为
HTTP 429（频率限制）最多重试 2 次
HTTP 5xx（服务器错误）最多重试 2 次
网络错误 / 超时最多重试 2 次
HTTP 401 / 403不重试 — 立即抛出 AuthError
HTTP 4xx（其他）不重试 — 立即抛出 ApiError

退避： 重试间隔 2^retryCount 秒（2s → 4s）。最坏情况：3 次尝试。

取消请求（TypeScript）

传入 AbortSignal 取消进行中的请求：

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);


try {
  const result = await client.marketplace.listProducts(
    { page: 1 },
    { signal: controller.signal },
  );
} catch (e) {
  if (e instanceof NetworkError && e.message.includes("aborted")) {
    console.log("请求已被取消");
  }
}

异步错误处理（Python）

async 客户端抛出相同的异常类型：

from imbrace import AsyncImbraceClient, AuthError, ApiError


async with AsyncImbraceClient() as client:
    try:
        me = await client.platform.get_me()
    except AuthError:
        print("需要重新认证")
    except ApiError as e:
        print(f"[{e.status_code}] {e}")

最佳实践

// 1. 单独处理 AuthError — 凭证需要刷新
// 2. 记录 ApiError.statusCode — 400=参数错误，404=未找到，409=冲突
// 3. 在顶层入口点用 try/catch 包装
// 4. AuthError 时不要重试 — 在修复凭证之前重试无效


async function safeGetMe(client: ImbraceClient) {
  try {
    return await client.platform.getMe();
  } catch (e) {
    if (e instanceof AuthError) {
      await refreshCredentials();
      return await client.platform.getMe();
    }
    throw e;
  }
}