Error Handling

Gestire con eleganza gli errori in produzione per prevenire i fallimenti silenziosi. Quando una chiamata come getResult() fallisce, l'SDK lancia un TracioError — una sottoclasse di Error con un campo code leggibile dalla macchina.

Catturare gli errori

Racchiudere await tracio.getResult() in un try/catch e restringere il valore lanciato con isTracioError(), quindi ramificare in base a 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)) {
      // Fallimento transitorio (rete, timeout, script bloccato, upstream) —
      // un nuovo tentativo potrebbe riuscire.
      console.warn(`Retryable TRACIO error: ${error.code}`)
    } else {
      // Fallimento terminale (configurazione errata, uso improprio, istanza distrutta) —
      // correggere il chiamante; riprovare la stessa chiamata non aiuterà.
      console.error(`Terminal TRACIO error: ${error.code} — ${error.message}`)
    }
  } else {
    console.error("Unexpected error:", error)
  }
}

La callback onError

L'agente si carica in modo asincrono in background. Se il caricamento fallisce prima ancora di chiamare getResult(), il fallimento viene consegnato tramite la callback onError. Registrarla subito dopo init():

TypeScript

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

tracio.onError((error) => {
  // La stessa istanza di TracioError che si catturerebbe da getResult().
  console.warn(`TRACIO failed to initialize: ${error.code}`)
})

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

Lo stesso errore rimane osservabile tramite getResult() — è possibile usare uno dei due canali.

Codici di errore

Ogni TracioError reca un code di tipo TracioErrorCode. Il getter retryable (e l'helper isRetryableError()) indica se un nuovo tentativo potrebbe riuscire.

Codice	Significato	Ripetibile
`invalid_config`	La configurazione passata a `Tracio.init()` non è valida	No
`multiple_keys`	Più di una chiave pubblica è stata usata sulla stessa pagina	No
`non_browser`	`getResult()` è stato atteso al di fuori di un browser (ad es. sul server)	No
`load_failed`	Il caricamento dello script dell'agente è fallito	Sì
`blocked`	Lo script è stato bloccato (ad blocker o CSP)	Sì
`script_error`	Lo script caricato ha lanciato un errore durante l'inizializzazione	Sì
`network`	Fallimento di rete/trasporto nel raggiungere l'API	Sì
`timeout`	La chiamata ha superato il budget `timeoutMs` configurato	Sì
`server`	L'edge/server ha restituito un fallimento upstream	Sì
`destroyed`	L'istanza è stata distrutta (tramite `destroy()`) prima della chiamata	No

I codici terminali (invalid_config, multiple_keys, non_browser, destroyed) indicano un problema di configurazione, di utilizzo o di ciclo di vita — correggere il chiamante o chiamare nuovamente Tracio.init(). I codici ripetibili sono transitori e un nuovo tentativo potrebbe riuscire.

Strategia di retry

Per gli errori ripetibili, riprovare con backoff su un nuovo tentativo anziché attendere di nuovo la stessa promise rifiutata:

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++
      // Smontare prima di riprovare: init() restituisce l'istanza in cache per la
      // stessa chiave, e getResult() mette in cache la sua promise (rifiutata) — quindi un
      // vero nuovo tentativo richiede prima destroy().
      tracio.destroy()
      if (!isRetryableError(error) || attempt >= maxAttempts) throw error
      await new Promise((r) => setTimeout(r, 2 ** attempt * 250))
    }
  }
}

Catturare gli errori

Racchiudere await tracio.getResult() in un try/catch e restringere il valore lanciato con isTracioError(), quindi ramificare in base a 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)) {
      // Fallimento transitorio (rete, timeout, script bloccato, upstream) —
      // un nuovo tentativo potrebbe riuscire.
      console.warn(`Retryable TRACIO error: ${error.code}`)
    } else {
      // Fallimento terminale (configurazione errata, uso improprio, istanza distrutta) —
      // correggere il chiamante; riprovare la stessa chiamata non aiuterà.
      console.error(`Terminal TRACIO error: ${error.code} — ${error.message}`)
    }
  } else {
    console.error("Unexpected error:", error)
  }
}

La callback onError

TypeScript

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

tracio.onError((error) => {
  // La stessa istanza di TracioError che si catturerebbe da getResult().
  console.warn(`TRACIO failed to initialize: ${error.code}`)
})

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

Lo stesso errore rimane osservabile tramite getResult() — è possibile usare uno dei due canali.

Codici di errore

Ogni TracioError reca un code di tipo TracioErrorCode. Il getter retryable (e l'helper isRetryableError()) indica se un nuovo tentativo potrebbe riuscire.

Codice

Significato

Ripetibile

invalid_config

La configurazione passata a Tracio.init() non è valida

multiple_keys

Più di una chiave pubblica è stata usata sulla stessa pagina

non_browser

getResult() è stato atteso al di fuori di un browser (ad es. sul server)

load_failed

Il caricamento dello script dell'agente è fallito

Sì

blocked

Lo script è stato bloccato (ad blocker o CSP)

Sì

script_error

Lo script caricato ha lanciato un errore durante l'inizializzazione

Sì

network

Fallimento di rete/trasporto nel raggiungere l'API

Sì

timeout

La chiamata ha superato il budget timeoutMs configurato

Sì

server

L'edge/server ha restituito un fallimento upstream

Sì

destroyed

L'istanza è stata distrutta (tramite destroy()) prima della chiamata

Strategia di retry

Per gli errori ripetibili, riprovare con backoff su un nuovo tentativo anziché attendere di nuovo la stessa promise rifiutata:

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++
      // Smontare prima di riprovare: init() restituisce l'istanza in cache per la
      // stessa chiave, e getResult() mette in cache la sua promise (rifiutata) — quindi un
      // vero nuovo tentativo richiede prima destroy().
      tracio.destroy()
      if (!isRetryableError(error) || attempt >= maxAttempts) throw error
      await new Promise((r) => setTimeout(r, 2 ** attempt * 250))
    }
  }
}