Error Handling

Trate erros de forma elegante em produção para evitar falhas silenciosas. Quando uma chamada como getResult() falha, o SDK lança um TracioError — uma subclasse de Error com um campo code legível por máquina.

Capturando erros

Envolva await tracio.getResult() em um try/catch e restrinja o valor lançado com isTracioError(), então ramifique com base em 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)
  }
}

O callback onError

O agente carrega de forma assíncrona em segundo plano. Se o carregamento falhar antes mesmo de você chamar getResult(), a falha é entregue através do callback onError. Registre-o logo após o 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)
})

O mesmo erro permanece observável através de getResult() — você pode usar qualquer um dos canais.

Códigos de erro

Todo TracioError carrega um code do tipo TracioErrorCode. O getter retryable (e o helper isRetryableError()) informa se uma nova tentativa pode ter sucesso.

Código	Significado	Retryable
`invalid_config`	A config passada para `Tracio.init()` é inválida	Não
`multiple_keys`	Mais de uma chave pública foi usada na mesma página	Não
`non_browser`	`getResult()` foi aguardado fora de um navegador (ex.: no servidor)	Não
`load_failed`	O script do agente falhou ao carregar	Sim
`blocked`	O script foi bloqueado (bloqueador de anúncios ou CSP)	Sim
`script_error`	O script carregado lançou um erro durante a inicialização	Sim
`network`	Falha de rede/transporte ao alcançar a API	Sim
`timeout`	A chamada excedeu o orçamento de `timeoutMs` configurado	Sim
`server`	O edge/servidor retornou uma falha upstream	Sim
`destroyed`	A instância foi destruída (via `destroy()`) antes da chamada	Não

Códigos terminais (invalid_config, multiple_keys, non_browser, destroyed) indicam um problema de configuração, uso ou ciclo de vida — corrija o chamador ou chame Tracio.init() novamente. Códigos retryable são transitórios e uma nova tentativa pode ter sucesso.

Estratégia de retry

Para erros retryable, tente novamente com backoff em uma nova tentativa, em vez de aguardar novamente a mesma promise rejeitada:

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

Capturando erros

Envolva await tracio.getResult() em um try/catch e restrinja o valor lançado com isTracioError(), então ramifique com base em 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)
  }
}

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

O mesmo erro permanece observável através de getResult() — você pode usar qualquer um dos canais.

Códigos de erro

Todo TracioError carrega um code do tipo TracioErrorCode. O getter retryable (e o helper isRetryableError()) informa se uma nova tentativa pode ter sucesso.

Código

Significado

Retryable

invalid_config

A config passada para Tracio.init() é inválida

Não

multiple_keys

Mais de uma chave pública foi usada na mesma página

Não

non_browser

getResult() foi aguardado fora de um navegador (ex.: no servidor)

Não

load_failed

O script do agente falhou ao carregar

Sim

blocked

O script foi bloqueado (bloqueador de anúncios ou CSP)

Sim

script_error

O script carregado lançou um erro durante a inicialização

Sim

network

Falha de rede/transporte ao alcançar a API

Sim

timeout

A chamada excedeu o orçamento de timeoutMs configurado

Sim

server

O edge/servidor retornou uma falha upstream

Sim

destroyed

A instância foi destruída (via destroy()) antes da chamada

Não

Estratégia de retry

Para erros retryable, tente novamente com backoff em uma nova tentativa, em vez de aguardar novamente a mesma promise rejeitada:

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