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: Không tìm thấy liên hệ"
  }
}
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ụ: "Yêu cầu đã hết thời gian sau 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. Số lần thử lại khác nhau đôi chút giữa các ngôn ngữ nhưng các điều kiện thì giống hệt nhau.

Điều kiệnHành động
HTTP 429 (giới hạn tốc độ)Thử lại tối đa 2 lần
HTTP 5xx (lỗi máy chủ)Thử lại tối đa 2 lần
Lỗi mạng / hết thời gianThử lại tối đa 2 lần
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

Backoff: 2^sốLầnThửLại giây giữa các lần thử (2s → 4s). Tổng tệ nhất: 3 lần thử.

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