Skip to main content
SDK cung cấp hai lớp lỗi: YoukaRequestError cho lỗi HTTP và lỗi xác thực (validation), và YoukaTaskError cho các tác vụ bất đồng bộ kết thúc ở trạng thái không thành công. Cả hai đều kế thừa Error và mang theo các trường có cấu trúc để bạn có thể rẽ nhánh theo code, status và khả năng thử lại (retryability).

​
YoukaRequestError

Được ném ra khi gặp lỗi HTTP, lỗi xác thực request, và phản hồi bị sai định dạng. 
import { YoukaRequestError } from "@youka/sdk";

try {
  await client.projects.create(body);
} catch (error) {
  if (error instanceof YoukaRequestError) {
    console.error({
      code: error.code,
      message: error.message,
      status: error.status,
      retryable: error.retryable,
      details: error.details,
    });
  } else {
    throw error;
  }
}

​
Các trường

​
code
string
Mã lỗi có thể đọc bởi máy, ví dụ INVALID_REQUEST, UNAUTHORIZED, UPLOAD_FAILED.
​
message
string
Mô tả dành cho con người.
​
status
number
Mã trạng thái HTTP, nếu có.
​
retryable
boolean
true nếu SDK coi lỗi này đáng để thử lại (giới hạn tốc độ, lỗi máy chủ tạm thời, đang phát lại theo idempotent).
​
details
unknown
Chi tiết do server cung cấp, thường là danh sách issue của Zod đối với lỗi validation.

​
Các code thường gặp

CodeNguyên nhânCó thể thử lại?
INVALID_REQUESTBody của request không vượt qua kiểm tra schema trước khi được gửi đi.No
UNAUTHORIZEDThiếu hoặc API key không hợp lệ.No
NOT_FOUNDTài nguyên không tồn tại hoặc bạn không có quyền truy cập.No
CONFLICTXung đột phiên bản (HTTP 409).Yes
TOO_MANY_REQUESTSChạm giới hạn tốc độ (HTTP 429).Yes
INTERNAL_SERVER_ERRORLỗi máy chủ tạm thời (HTTP 500).Yes
IDEMPOTENT_REPLAY_IN_PROGRESSRequest gốc vẫn đang chạy dưới cùng idempotency key (HTTP 202).Yes
INVALID_RESPONSEServer trả về body không khớp với schema mong đợi.No
UPLOAD_FAILEDUpload qua signed URL trả về mã khác 2xx.Phụ thuộc vào status

​
YoukaTaskError

Được ném ra từ client.tasks.wait(...), client.projects.wait(...), và client.exports.wait(...) khi tác vụ hoặc export bên dưới kết thúc ở failed, cancelled, hoặc timed-out. 
import { YoukaTaskError } from "@youka/sdk";

try {
  await client.projects.wait(created);
} catch (error) {
  if (error instanceof YoukaTaskError) {
    console.error({
      code: error.code,
      message: error.message,
      status: error.status,
      task: error.task,
    });
  } else {
    throw error;
  }
}

​
Các trường

​
code
'TASK_FAILED' | 'TASK_CANCELLED' | 'TASK_TIMED_OUT'
Ánh xạ trực tiếp tới trạng thái kết thúc (terminal status) của tác vụ.
​
message
string
Hoặc là thông điệp lỗi của tác vụ do server cung cấp, hoặc là một thông điệp dự phòng được tạo ra.
​
status
TaskStatus
Trạng thái kết thúc của tác vụ.
​
task
RestTask
Toàn bộ payload của tác vụ tại thời điểm thất bại. Hữu ích cho việc ghi log và thông báo lỗi hiển thị cho người dùng.

​
Mẫu retry

Kết hợp retryable với một idempotency key để xây dựng vòng lặp retry an toàn: 
import { YoukaRequestError } from "@youka/sdk";

async function createWithRetry<T>(fn: () => Promise<T>, maxAttempts = 3) {
  let lastError: unknown;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
      if (
        error instanceof YoukaRequestError &&
        error.retryable &&
        attempt < maxAttempts
      ) {
        await new Promise((r) => setTimeout(r, 2 ** attempt * 1_000));
        continue;
      }
      throw error;
    }
  }

  throw lastError;
}

await createWithRetry(() =>
  client.projects.create(body, {
    idempotencyKey: "import-2026-04-08-song-001",
  }),
);
Luôn dùng lại cùng một idempotency key giữa các lần retry. Nếu không, server sẽ coi lần retry là một request mới và bạn có thể bị tạo trùng.

​
Hủy (abort) và huỷ tác vụ

Khi abort một request sẽ ném ra AbortError tiêu chuẩn — không phải YoukaRequestError. Hãy kiểm tra riêng trường hợp này: 
try {
  await client.projects.wait(created, { signal: controller.signal });
} catch (error) {
  if (error instanceof Error && error.name === "AbortError") {
    console.log("Cancelled by user");
    return;
  }
  throw error;
}

​
Tiếp theo

  • Tasks — các helper để chờ và polling tác vụ nâng cao
  • Authentication — các tuỳ chọn constructor và signal
  • API errors — các code tương tự ở dạng HTTP thô