Xử lý lỗi

Xử lý lỗi một cách gọn gàng trong môi trường production để tránh các sự cố âm thầm. Khi một lệnh gọi như getResult() thất bại, SDK sẽ ném ra một TracioError — một lớp con của Error với trường code có thể đọc được bằng máy.

Bắt lỗi

Bọc await tracio.getResult() trong try/catch và thu hẹp giá trị được ném ra bằng isTracioError(), sau đó phân nhánh theo error.code:

TypeScript

import { Tracio, isTracioError, isRetryableError } from "@tracio/sdk"

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

try {
  const result = await tracio.getResult()
  console.log(result.visitorId, result.bot.detected)
} catch (error) {
  if (isTracioError(error)) {
    if (isRetryableError(error)) {
      // Transient failure (network, timeout, blocked script, upstream) —
      // a fresh attempt may succeed.
      console.warn(`Retryable TRACIO error: ${error.code}`)
    } else {
      // Terminal failure (bad config, misuse, destroyed instance) —
      // fix the caller; retrying the same call will not help.
      console.error(`Terminal TRACIO error: ${error.code} — ${error.message}`)
    }
  } else {
    console.error("Unexpected error:", error)
  }
}

Callback onError

Agent được tải bất đồng bộ ở chế độ nền. Nếu quá trình tải thất bại trước khi bạn kịp gọi getResult(), lỗi sẽ được chuyển qua callback onError. Hãy đăng ký nó ngay sau init():

TypeScript

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

tracio.onError((error) => {
  // Same TracioError instance you would catch from getResult().
  console.warn(`TRACIO failed to initialize: ${error.code}`)
})

tracio.onReady((result) => {
  console.log("Visitor identified:", result.visitorId)
})

Cùng một lỗi đó vẫn có thể quan sát được qua getResult() — bạn có thể dùng một trong hai kênh.

Mã lỗi

Mỗi TracioError mang theo một code thuộc kiểu TracioErrorCode. Getter retryable (và hàm hỗ trợ isRetryableError()) cho biết liệu một lần thử mới có thể thành công hay không.

Code	Ý nghĩa	Có thể thử lại
`invalid_config`	Cấu hình truyền vào `Tracio.init()` không hợp lệ	Không
`multiple_keys`	Có nhiều hơn một public key được dùng trên cùng một trang	Không
`non_browser`	`getResult()` được await bên ngoài trình duyệt (ví dụ trên server)	Không
`load_failed`	Script của agent không tải được	Có
`blocked`	Script bị chặn (trình chặn quảng cáo hoặc CSP)	Có
`script_error`	Script đã tải ném ra lỗi khi khởi tạo	Có
`network`	Lỗi mạng/truyền tải khi kết nối tới API	Có
`timeout`	Lệnh gọi vượt quá ngân sách `timeoutMs` đã cấu hình	Có
`server`	Edge/server trả về lỗi upstream	Có
`destroyed`	Instance đã bị hủy (qua `destroy()`) trước khi gọi	Không

Các mã cuối cùng (invalid_config, multiple_keys, non_browser, destroyed) cho thấy một vấn đề về cấu hình, cách sử dụng hoặc vòng đời — hãy sửa phía gọi hoặc gọi lại Tracio.init(). Các mã có thể thử lại là tạm thời và một lần thử mới có thể thành công.

Chiến lược thử lại

Đối với các lỗi có thể thử lại, hãy thử lại với backoff bằng một lần thử mới thay vì await lại cùng một promise đã bị từ chối:

TypeScript

import { Tracio, isRetryableError } from "@tracio/sdk"

async function identifyWithRetry(maxAttempts = 3) {
  let attempt = 0
  while (true) {
    const tracio = Tracio.init({ publicKey: "5ca175fc..." })
    try {
      return await tracio.getResult()
    } catch (error) {
      attempt++
      // Tear down before retrying: init() returns the cached instance for the
      // same key, and getResult() caches its (rejected) promise — so a genuine
      // fresh attempt requires destroy() first.
      tracio.destroy()
      if (!isRetryableError(error) || attempt >= maxAttempts) throw error
      await new Promise((r) => setTimeout(r, 2 ** attempt * 250))
    }
  }
}

Bắt lỗi

Bọc await tracio.getResult() trong try/catch và thu hẹp giá trị được ném ra bằng isTracioError(), sau đó phân nhánh theo error.code:

TypeScript

import { Tracio, isTracioError, isRetryableError } from "@tracio/sdk"

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

try {
  const result = await tracio.getResult()
  console.log(result.visitorId, result.bot.detected)
} catch (error) {
  if (isTracioError(error)) {
    if (isRetryableError(error)) {
      // Transient failure (network, timeout, blocked script, upstream) —
      // a fresh attempt may succeed.
      console.warn(`Retryable TRACIO error: ${error.code}`)
    } else {
      // Terminal failure (bad config, misuse, destroyed instance) —
      // fix the caller; retrying the same call will not help.
      console.error(`Terminal TRACIO error: ${error.code} — ${error.message}`)
    }
  } else {
    console.error("Unexpected error:", error)
  }
}

Callback onError

TypeScript

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

tracio.onError((error) => {
  // Same TracioError instance you would catch from getResult().
  console.warn(`TRACIO failed to initialize: ${error.code}`)
})

tracio.onReady((result) => {
  console.log("Visitor identified:", result.visitorId)
})

Cùng một lỗi đó vẫn có thể quan sát được qua getResult() — bạn có thể dùng một trong hai kênh.

Mã lỗi

Code

Ý nghĩa

Có thể thử lại

invalid_config

Cấu hình truyền vào Tracio.init() không hợp lệ

Không

multiple_keys

Có nhiều hơn một public key được dùng trên cùng một trang

Không

non_browser

getResult() được await bên ngoài trình duyệt (ví dụ trên server)

Không

load_failed

Script của agent không tải được

Có

blocked

Script bị chặn (trình chặn quảng cáo hoặc CSP)

Có

script_error

Script đã tải ném ra lỗi khi khởi tạo

Có

network

Lỗi mạng/truyền tải khi kết nối tới API

Có

timeout

Lệnh gọi vượt quá ngân sách timeoutMs đã cấu hình

Có

server

Edge/server trả về lỗi upstream

Có

destroyed

Instance đã bị hủy (qua destroy()) trước khi gọi

Không

Chiến lược thử lại

Đối với các lỗi có thể thử lại, hãy thử lại với backoff bằng một lần thử mới thay vì await lại cùng một promise đã bị từ chối:

TypeScript

import { Tracio, isRetryableError } from "@tracio/sdk"

async function identifyWithRetry(maxAttempts = 3) {
  let attempt = 0
  while (true) {
    const tracio = Tracio.init({ publicKey: "5ca175fc..." })
    try {
      return await tracio.getResult()
    } catch (error) {
      attempt++
      // Tear down before retrying: init() returns the cached instance for the
      // same key, and getResult() caches its (rejected) promise — so a genuine
      // fresh attempt requires destroy() first.
      tracio.destroy()
      if (!isRetryableError(error) || attempt >= maxAttempts) throw error
      await new Promise((r) => setTimeout(r, 2 ** attempt * 250))
    }
  }
}