Error Handling

Behandel fouten netjes in productie om stille storingen te voorkomen. Wanneer een aanroep zoals getResult() mislukt, werpt de SDK een TracioError — een subklasse van Error met een machineleesbaar code-veld.

Fouten opvangen

Omhul await tracio.getResult() met een try/catch en verklein de geworpen waarde met isTracioError(), en vertak vervolgens op 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)
  }
}

De onError-callback

De agent laadt asynchroon op de achtergrond. Als het laden mislukt voordat u ooit getResult() aanroept, wordt de fout afgeleverd via de onError-callback. Registreer deze direct na 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)
})

Dezelfde fout blijft waarneembaar via getResult() — u kunt beide kanalen gebruiken.

Foutcodes

Elke TracioError draagt een code van het type TracioErrorCode. De retryable-getter (en de hulpfunctie isRetryableError()) geven aan of een nieuwe poging kan slagen.

Code	Betekenis	Retryable
`invalid_config`	De aan `Tracio.init()` doorgegeven config is ongeldig	Nee
`multiple_keys`	Meer dan één public key werd op dezelfde pagina gebruikt	Nee
`non_browser`	`getResult()` werd buiten een browser awaited (bijv. op de server)	Nee
`load_failed`	Het agent-script kon niet worden geladen	Ja
`blocked`	Het script werd geblokkeerd (adblocker of CSP)	Ja
`script_error`	Het geladen script wierp een fout tijdens het initialiseren	Ja
`network`	Netwerk-/transportfout bij het bereiken van de API	Ja
`timeout`	De aanroep overschreed het geconfigureerde `timeoutMs`-budget	Ja
`server`	De edge/server gaf een upstream-fout terug	Ja
`destroyed`	De instantie werd vernietigd (via `destroy()`) vóór de aanroep	Nee

Terminale codes (invalid_config, multiple_keys, non_browser, destroyed) duiden op een configuratie-, gebruiks- of levenscyclusprobleem — herstel de aanroeper of roep Tracio.init() opnieuw aan. Retryable-codes zijn tijdelijk en een nieuwe poging kan slagen.

Retry-strategie

Herhaal bij retryable fouten met backoff via een nieuwe poging, in plaats van dezelfde afgewezen promise opnieuw te awaiten:

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

Fouten opvangen

Omhul await tracio.getResult() met een try/catch en verklein de geworpen waarde met isTracioError(), en vertak vervolgens op 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)
  }
}

De onError-callback

De agent laadt asynchroon op de achtergrond. Als het laden mislukt voordat u ooit getResult() aanroept, wordt de fout afgeleverd via de onError-callback. Registreer deze direct na 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)
})

Dezelfde fout blijft waarneembaar via getResult() — u kunt beide kanalen gebruiken.

Foutcodes

Elke TracioError draagt een code van het type TracioErrorCode. De retryable-getter (en de hulpfunctie isRetryableError()) geven aan of een nieuwe poging kan slagen.

Code

Betekenis

Retryable

invalid_config

De aan Tracio.init() doorgegeven config is ongeldig

Nee

multiple_keys

Meer dan één public key werd op dezelfde pagina gebruikt

Nee

non_browser

getResult() werd buiten een browser awaited (bijv. op de server)

Nee

load_failed

Het agent-script kon niet worden geladen

blocked

Het script werd geblokkeerd (adblocker of CSP)

script_error

Het geladen script wierp een fout tijdens het initialiseren

network

Netwerk-/transportfout bij het bereiken van de API

timeout

De aanroep overschreed het geconfigureerde timeoutMs-budget

server

De edge/server gaf een upstream-fout terug

destroyed

De instantie werd vernietigd (via destroy()) vóór de aanroep

Nee

Retry-strategie

Herhaal bij retryable fouten met backoff via een nieuwe poging, in plaats van dezelfde afgewezen promise opnieuw te awaiten:

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