Manejo de errores

Maneje los errores con elegancia en producción para evitar fallos silenciosos. Cuando una llamada como getResult() falla, el SDK lanza un TracioError: una subclase de Error con un campo code legible por máquina.

Captura de errores

Envuelva await tracio.getResult() en un try/catch y acote el valor lanzado con isTracioError(), luego ramifique según 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)
  }
}

El callback onError

El agente se carga de forma asíncrona en segundo plano. Si la carga falla antes de que llegue a llamar a getResult(), el fallo se entrega a través del callback onError. Regístrelo justo después de 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)
})

El mismo error sigue siendo observable a través de getResult(): puede usar cualquiera de los dos canales.

Códigos de error

Todo TracioError lleva un code de tipo TracioErrorCode. El getter retryable (y el helper isRetryableError()) indican si un nuevo intento puede tener éxito.

Código	Significado	¿Reintentable?
`invalid_config`	La configuración pasada a `Tracio.init()` no es válida	No
`multiple_keys`	Se usó más de una clave pública en la misma página	No
`non_browser`	Se esperó `getResult()` fuera de un navegador (p. ej. en el servidor)	No
`load_failed`	El script del agente no se pudo cargar	Sí
`blocked`	El script fue bloqueado (bloqueador de anuncios o CSP)	Sí
`script_error`	El script cargado lanzó un error al inicializarse	Sí
`network`	Fallo de red o de transporte al alcanzar la API	Sí
`timeout`	La llamada superó el presupuesto configurado de `timeoutMs`	Sí
`server`	El edge/servidor devolvió un fallo upstream	Sí
`destroyed`	La instancia fue destruida (con `destroy()`) antes de la llamada	No

Los códigos terminales (invalid_config, multiple_keys, non_browser, destroyed) indican un problema de configuración, uso o ciclo de vida: corrija el código que hace la llamada o llame a Tracio.init() de nuevo. Los códigos reintentables son transitorios y un nuevo intento puede tener éxito.

Estrategia de reintento

Para los errores reintentables, reintente con backoff sobre un nuevo intento en lugar de volver a esperar la misma promesa rechazada:

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

Captura de errores

Envuelva await tracio.getResult() en un try/catch y acote el valor lanzado con isTracioError(), luego ramifique según 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)
  }
}

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

El mismo error sigue siendo observable a través de getResult(): puede usar cualquiera de los dos canales.

Códigos de error

Todo TracioError lleva un code de tipo TracioErrorCode. El getter retryable (y el helper isRetryableError()) indican si un nuevo intento puede tener éxito.

Código

Significado

¿Reintentable?

invalid_config

La configuración pasada a Tracio.init() no es válida

multiple_keys

Se usó más de una clave pública en la misma página

non_browser

Se esperó getResult() fuera de un navegador (p. ej. en el servidor)

load_failed

El script del agente no se pudo cargar

Sí

blocked

El script fue bloqueado (bloqueador de anuncios o CSP)

Sí

script_error

El script cargado lanzó un error al inicializarse

Sí

network

Fallo de red o de transporte al alcanzar la API

Sí

timeout

La llamada superó el presupuesto configurado de timeoutMs

Sí

server

El edge/servidor devolvió un fallo upstream

Sí

destroyed

La instancia fue destruida (con destroy()) antes de la llamada

Estrategia de reintento

Para los errores reintentables, reintente con backoff sobre un nuevo intento en lugar de volver a esperar la misma promesa rechazada:

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