Chuyển đến nội dung
Imbrace SDK

Xử lý Lỗi

Tất cả các lỗi do SDK đưa ra đều mở rộng từ một kiểu cơ sở duy nhất, vì vậy bạn có thể bắt bất kỳ lỗi SDK nào ở một nơi hoặc phân nhánh theo lớp con cụ thể khi bạn cần phản ứng khác nhau. Hệ thống phân cấp giống hệt nhau trong SDK TypeScript và Python.

Hệ thống phân cấp lỗi

Error
└── ImbraceError          (cơ sở — bắt tất cả lỗi SDK)
    ├── AuthError          (401, 403 — thông tin xác thực không hợp lệ hoặc hết hạn)
    ├── ApiError           (4xx/5xx — yêu cầu bị máy chủ từ chối)
    └── NetworkError       (hết thời gian, từ chối kết nối, lỗi DNS)

Để biết các thông báo lỗi cụ thể và cách khắc phục đã biết, xem Khắc phục sự cố.

AuthError

Được đưa ra khi máy chủ trả về 401 hoặc 403 — thông tin xác thực không hợp lệ, hết hạn hoặc bị thu hồi.

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


try {
  const me = await client.platform.getMe();
} catch (e) {
  if (e instanceof AuthError) {
    console.error("Cần xác thực lại:", e.message);
  }
}

ApiError

Được đưa ra cho tất cả các phản hồi 4xx và 5xx khác (sau khi đã thử lại hết cho 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}`);
    // ví dụ: "HTTP 404: Contact not found"
  }
}
Thuộc tínhLoạiMô tả
statusCodenumberMã trạng thái HTTP
messagestringThông báo lỗi từ phản hồi máy chủ

NetworkError

Được đưa ra khi yêu cầu không bao giờ đến được máy chủ — hết thời gian, lỗi DNS hoặc kết nối bị reset.

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


try {
  await client.platform.getMe();
} catch (e) {
  if (e instanceof NetworkError) {
    console.error("Không thể kết nối baseUrl:", e.message);
    // ví dụ: "Request timed out after 30000ms"
  }
}

Bắt tất cả lỗi SDK

Import kiểu cơ sở để xử lý bất kỳ lỗi nào từ SDK trong một khối duy nhất:

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; // ném lại lỗi không phải SDK
}

Hành vi thử lại tự động

Tầng vận chuyển HTTP trong cả hai SDK đều thử lại các lỗi tạm thời với exponential backoff.

Điều kiệnHành động
HTTP 429 / 503Thử lại tối đa 3 lần, mọi method
HTTP 5xx (khác)Thử lại tối đa 3 lần với GET, HEAD, OPTIONS, PUT, DELETE
Lỗi mạng / hết thời gianThử lại tối đa 3 lần với GET, HEAD, OPTIONS, PUT, DELETE
HTTP 401 / 403Không thử lại — ném AuthError ngay lập tức
HTTP 4xx (khác)Không thử lại — ném ApiError ngay lập tức

POST và PATCH không được thử lại khi hết thời gian, lỗi mạng hoặc 5xx khác 503, vì máy chủ có thể đã thực thi chúng.

Backoff: với 429/503, SDK chờ theo header Retry-After (số giây hoặc ngày HTTP) nếu máy chủ gửi, tối đa 60 giây; Retry-After dài hơn thì ném ApiError ngay. Nếu không có header: 2^retryCount giây giữa các lần thử (1s → 2s → 4s). Trường hợp xấu nhất: tổng cộng 4 lần thử.

Cấu hình (1.7.0+): maxRetries đặt số lần thử lại (0 = chỉ một lần gọi). fetch thay fetch dùng cho mọi request, ví dụ để tự thêm lớp retry, proxy hoặc tracing.

const client = new ImbraceClient({
  apiKey: process.env.IMBRACE_API_KEY,
  maxRetries: 0,      // SDK chỉ gọi một lần; tự retry ở lớp của bạn
  fetch: myFetch,     // tuỳ chọn
});

Thời gian chờ yêu cầu

Cấu hình thời gian chờ khi tạo client (mặc định: 30 s). Khi hết thời gian chờ, yêu cầu đang thực hiện sẽ bị hủy và NetworkError được ném/đưa ra.

const client = new ImbraceClient({ timeout: 15_000 }); // mili giây

Xử lý lỗi bất đồng bộ (Python)

Client bất đồng bộ đưa ra các loại ngoại lệ giống hệt nhau:

from imbrace import AsyncImbraceClient, AuthError, ApiError


async with AsyncImbraceClient() as client:
    try:
        me = await client.platform.get_me()
    except AuthError:
        print("Cần xác thực lại")
    except ApiError as e:
        print(f"[{e.status_code}] {e}")

Phương pháp tốt nhất

// 1. Luôn xử lý AuthError riêng — cần làm mới thông tin xác thực
// 2. Ghi log ApiError.statusCode — 400 = tham số sai, 404 = không tìm thấy, 409 = xung đột
// 3. Bọc các điểm vào cấp cao nhất trong try/catch
// 4. Không thử lại AuthError — sẽ không giúp ích cho đến khi thông tin xác thực được sửa


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;
  }
}