跳到內容
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("Re-authenticate:", e.message);
  }
}

ApiError

在所有其他 4xx 和 5xx 回應（在 429/5xx 的重試耗盡後）時拋出。

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


try {
  await client.contacts.get("nonexistent_id");
} catch (e) {
  if (e instanceof ApiError) {
    console.error(`HTTP ${e.statusCode}: ${e.message}`);
    // e.g. "HTTP 404: Contact not found"
  }
}
屬性類型說明
statusCodenumberHTTP 狀態碼
messagestring來自伺服器回應的錯誤訊息

NetworkError

當請求從未到達伺服器時拋出 — 逾時、DNS 失敗或連線重置。

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


try {
  await client.platform.getMe();
} catch (e) {
  if (e instanceof NetworkError) {
    console.error("Cannot reach baseUrl:", e.message);
    // e.g. "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 傳輸層都會以指數退避重試暫時性失敗。

條件動作
HTTP 429 / 503最多重試 3 次，所有方法
HTTP 5xx（其他）GET、HEAD、OPTIONS、PUT、DELETE 最多重試 3 次
網路錯誤 / 逾時GET、HEAD、OPTIONS、PUT、DELETE 最多重試 3 次
HTTP 401 / 403不重試 — 立即拋出 AuthError
HTTP 4xx（其他）不重試 — 立即拋出 ApiError

POST 和 PATCH 在逾時、網路錯誤或 503 以外的 5xx 時不會重試：伺服器可能已經執行了它們。

退避： 遇到 429/503 時，若伺服器回傳 Retry-After 標頭（秒數或 HTTP 日期），SDK 依其等待，最長 60 秒；更長的 Retry-After 會立即拋出 ApiError。否則嘗試之間間隔 2^retryCount 秒（1 秒 → 2 秒 → 4 秒）。最壞情況總計：4 次嘗試。

設定（1.7.0+）： maxRetries 設定重試次數（0 = 只嘗試一次）。fetch 取代所有請求使用的 fetch，例如加入你自己的重試、代理或追蹤層。

const client = new ImbraceClient({
  apiKey: process.env.IMBRACE_API_KEY,
  maxRetries: 0,      // SDK 只嘗試一次；在你自己的層中重試
  fetch: myFetch,     // 選用
});

請求逾時

在建立用戶端時設定逾時（預設：30 秒）。當逾時觸發時，進行中的請求將被中止並拋出/引發 NetworkError。

const client = new ImbraceClient({ timeout: 15_000 }); // 毫秒

非同步錯誤處理（Python）

非同步用戶端會拋出相同的例外類型：

from imbrace import AsyncImbraceClient, AuthError, ApiError


async with AsyncImbraceClient() as client:
    try:
        me = await client.platform.get_me()
    except AuthError:
        print("Re-authenticate")
    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;
  }
}