NodeJS

Xử lý lỗi

Các loại error và cách xử lý trong Node.js SDK

SDK sử dụng hệ thống error phân cấp. Tất cả error đều kế thừa từ SSIError, kế thừa từ Error chuẩn.

Danh sách Error

Error ClassKế thừaMô tả
SSIErrorErrorError cơ sở — có message, code, statusCode, responseBody (đã che secret), headers
APIErrorSSIErrorAPI trả về lỗi. code là mã lỗi của server, HTTP status nằm ở statusCode. HTTP 200 kèm code khác 200/204 cũng ném APIError
DuplicateRequestErrorAPIErrorHTTP 409: clientRequestId hoặc batchRequestId đã dùng (xem Batch Orders)
AuthenticationErrorSSIErrorXác thực thất bại (sai credentials, token hết hạn). Không kế thừa APIError
SmartOTPPendingErrorAuthenticationErrorSmart OTP chưa được duyệt (HTTP 202, code 401114)
SmartOTPRejectedErrorAuthenticationErrorSmart OTP bị từ chối
ReauthenticationRequiredAuthenticationErrorKhông refresh được phiên và không có OTP: cần xác thực lại bằng OTP
RateLimitErrorSSIErrorVượt quá giới hạn request — có thêm retryAfterMs (mili giây), limit, remaining, reset
WebSocketErrorSSIErrorLỗi kết nối hoặc giao tiếp WebSocket
TradingWSErrorWebSocketErrorServer của Trading WebSocket trả frame lỗi — có thêm status, errorCode, serverMessage
ValidationErrorSSIErrorLỗi validate input
ConfigurationErrorSSIErrorLỗi cấu hình (kể cả option không tồn tại)

Import

import {
  SSIError,
  APIError,
  DuplicateRequestError,
  AuthenticationError,
  SmartOTPPendingError,
  SmartOTPRejectedError,
  ReauthenticationRequired,
  RateLimitError,
  WebSocketError,
  TradingWSError,
  ValidationError,
  ConfigurationError,
} from '@ssi.developer/ssi-sdk';

Sử dụng cơ bản

try {
  const token = await auth.authenticate('wrong_otp');
} catch (error) {
  console.error(`Error: ${error.message}`);
}

Xử lý lỗi chi tiết

AuthenticationError không phải là APIError, nên thứ tự các nhánh instanceof không còn quan trọng giữa hai lớp này. Các lớp con (DuplicateRequestError, TradingWSError, SmartOTP*) cần được kiểm tra trước lớp cha nếu muốn xử lý riêng.

try {
  const result = await trading.trading.placeLimitOrder(
    'YOUR_ACCOUNT_NO', 'SSI', OrderSide.BUY, 100, 68000,
  );
} catch (error) {
  if (error instanceof ReauthenticationRequired) {
    console.log('Cần xác thực lại bằng OTP');
  } else if (error instanceof AuthenticationError) {
    console.log('Xác thực thất bại');
  } else if (error instanceof RateLimitError) {
    console.log(`Rate limited, retry sau ${error.retryAfterMs}ms`);
  } else if (error instanceof DuplicateRequestError) {
    console.log(`Trùng id (HTTP 409): ${error.message}`);
  } else if (error instanceof APIError) {
    console.log(`API error ${error.statusCode} (code ${error.code}): ${error.message}`);
  } else if (error instanceof ValidationError) {
    console.log(`Validation: ${error.message}`);
  } else if (error instanceof TradingWSError) {
    console.log(`Trading WS: status=${error.status} code=${error.errorCode} msg=${error.serverMessage}`);
  } else if (error instanceof WebSocketError) {
    console.log(`WebSocket: ${error.message}`);
  } else if (error instanceof ConfigurationError) {
    console.log(`Config: ${error.message}`);
  } else if (error instanceof SSIError) {
    console.log(`SDK error: ${error.message}`);
  } else {
    console.log(`Unknown error: ${error}`);
  }
}

Thuộc tính Error

SSIError / APIError

Thuộc tínhKiểuMô tả
messagestringThông báo lỗi
codestring | number?Mã lỗi (với APIError là mã của server)
statusCodenumber?HTTP status code
responseBodyunknown?Body response gốc (nếu có), đã che secret
headersRecord<string, string>Header response

RateLimitError

Thuộc tínhKiểuMô tả
messagestringThông báo lỗi
retryAfterMsnumber?Thời gian chờ trước khi retry (mili giây). Trước đây tên là retryAfter (giây)
limit, remaining, resetnumber?Thông tin rate limit server gửi kèm (nếu có)

code mặc định là 'RATE_LIMITED' và statusCode là 429. Với GET, REST client tự chờ khi gặp 429 (tối đa 3 lần retry, không bao giờ chờ quá 30 giây).

TradingWSError

Thuộc tínhKiểuMô tả
statusnumberStatus code trong frame lỗi (ví dụ 429)
errorCodestringMã lỗi server
serverMessagestringThông báo của server

Lỗi theo tính năng

Batch Orders

Xem cách dùng ở API Services, mục 5.6.

LỗiKhi nàoCách xử lý
ValidationErrorLô rỗng, vượt maxBatchOrders, hoặc một lệnh sai (thiếu field, clientRequestId quá dài, lệnh hủy không có đúng một id...)Sửa input. Chưa có request nào được gửi
DuplicateRequestErrorHTTP 409: clientRequestId hoặc batchRequestId đã dùng trong ngàyKiểm tra sổ lệnh, đừng gửi lại bằng id khác
AuthenticationErrorXác thực thất bại (sai credentials, token hết hạn)Xác thực lại bằng OTP
RateLimitErrorVượt giới hạn requestChờ rồi retry có kiểm soát
APIErrorLỗi server khác (có statusCode, code), ví dụ 400111 khi batchRequestTime ngoài cửa sổ replayĐọc code và message, không retry mù quáng

Lô không bao giờ bị retry tự động.

Trading WebSocket

Xem API Services, mục 7.4.

LỗiKhi nào
TradingWSErrorServer trả frame lỗi, hoặc từ chối kết nối sau khi đã nhận socket (HTTP 101). Có status, errorCode, serverMessage. Kế thừa WebSocketError
WebSocketErrorChưa kết nối, gửi thất bại, hết thời gian chờ phản hồi (không retry), socket đóng trước khi có phản hồi, hoặc thiếu private key cho lệnh đổi trạng thái
ValidationErrorInput sai bị bắt tại máy (ví dụ subscribe nhiều tài khoản, batch rỗng hoặc quá giới hạn). Vì method là async, lỗi này làm Promise bị reject

Status 429 từ server cho ra TradingWSError với status 429. Mã chữ ký bị từ chối 401006, 401008, 401013 được SDK thử lại một lần ở chế độ signatureEncoding: 'auto'.

Hướng dẫn xử lý

  • Dùng instanceof để xử lý từng loại error.
  • Bắt AuthenticationError khi cần làm mới token hoặc lấy OTP mới. ReauthenticationRequired nghĩa là bắt buộc phải xác thực lại bằng OTP.
  • Bắt RateLimitError và tuân thủ retryAfterMs để backoff.
  • Bắt APIError để xử lý lỗi nghiệp vụ từ server. Mã 401101-401104 và 401106-401108 (refresh token không dùng được) buộc phải xác thực lại.
  • Bắt WebSocketError khi xử lý kết nối streaming. connect() lần đầu thất bại ném WebSocketError hoặc AuthenticationError.
  • Bắt ValidationError để kiểm tra input trước khi gọi API.
  • Bắt ConfigurationError khi cấu hình thiếu hoặc không hợp lệ.
  • Dùng SSIError làm fallback cho tất cả lỗi SDK.

Trên trang này