Error Handling

Tratați erorile elegant în producție pentru a preveni eșecurile silențioase. Când un apel precum getResult() eșuează, SDK-ul aruncă un TracioError — o subclasă a Error cu un câmp code care poate fi citit de mașină.

Prinderea erorilor

Încadrați await tracio.getResult() într-un try/catch și restrângeți valoarea aruncată cu isTracioError(), apoi ramificați în funcție de 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-ul onError

Agentul se încarcă asincron în fundal. Dacă încărcarea eșuează înainte să apelați vreodată getResult(), eroarea este livrată prin callback-ul onError. Înregistrați-l imediat după 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)
})

Aceeași eroare rămâne observabilă prin getResult() — puteți folosi oricare dintre cele două canale.

Coduri de eroare

Fiecare TracioError poartă un code de tip TracioErrorCode. Getterul retryable (și funcția ajutătoare isRetryableError()) indică dacă o nouă încercare ar putea reuși.

Cod	Semnificație	Retryable
`invalid_config`	Configurația transmisă către `Tracio.init()` este invalidă	Nu
`multiple_keys`	Mai multe chei publice au fost folosite pe aceeași pagină	Nu
`non_browser`	`getResult()` a fost așteptat în afara unui browser (de ex. pe server)	Nu
`load_failed`	Scriptul agentului nu s-a putut încărca	Da
`blocked`	Scriptul a fost blocat (ad blocker sau CSP)	Da
`script_error`	Scriptul încărcat a aruncat o eroare la inițializare	Da
`network`	Eșec de rețea/transport la accesarea API-ului	Da
`timeout`	Apelul a depășit bugetul `timeoutMs` configurat	Da
`server`	Edge-ul/serverul a returnat un eșec upstream	Da
`destroyed`	Instanța a fost distrusă (prin `destroy()`) înainte de apel	Nu

Codurile terminale (invalid_config, multiple_keys, non_browser, destroyed) indică o problemă de configurare, utilizare sau ciclu de viață — reparați apelantul sau apelați din nou Tracio.init(). Codurile retryable sunt tranzitorii și o nouă încercare ar putea reuși.

Strategie de reîncercare

Pentru erorile retryable, reîncercați cu backoff printr-o nouă încercare, în loc să așteptați din nou aceeași promisiune respinsă:

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

Prinderea erorilor

Încadrați await tracio.getResult() într-un try/catch și restrângeți valoarea aruncată cu isTracioError(), apoi ramificați în funcție de 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-ul 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)
})

Aceeași eroare rămâne observabilă prin getResult() — puteți folosi oricare dintre cele două canale.

Coduri de eroare

Fiecare TracioError poartă un code de tip TracioErrorCode. Getterul retryable (și funcția ajutătoare isRetryableError()) indică dacă o nouă încercare ar putea reuși.

Cod

Semnificație

Retryable

invalid_config

Configurația transmisă către Tracio.init() este invalidă

multiple_keys

Mai multe chei publice au fost folosite pe aceeași pagină

non_browser

getResult() a fost așteptat în afara unui browser (de ex. pe server)

load_failed

Scriptul agentului nu s-a putut încărca

blocked

Scriptul a fost blocat (ad blocker sau CSP)

script_error

Scriptul încărcat a aruncat o eroare la inițializare

network

Eșec de rețea/transport la accesarea API-ului

timeout

Apelul a depășit bugetul timeoutMs configurat

server

Edge-ul/serverul a returnat un eșec upstream

destroyed

Instanța a fost distrusă (prin destroy()) înainte de apel

Strategie de reîncercare

Pentru erorile retryable, reîncercați cu backoff printr-o nouă încercare, în loc să așteptați din nou aceeași promisiune respinsă:

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