Error Handling

Hantera fel på ett kontrollerat sätt i produktion för att förhindra tysta fel. När ett anrop som getResult() misslyckas kastar SDK:t ett TracioError — en underklass till Error med ett maskinläsbart code-fält.

Fånga fel

Omslut await tracio.getResult() med try/catch och avgränsa det kastade värdet med isTracioError(), och förgrena sedan på 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)
  }
}

onError-callbacken

Agenten laddas asynkront i bakgrunden. Om laddningen misslyckas innan du någonsin anropar getResult() levereras felet via onError-callbacken. Registrera den direkt efter 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)
})

Samma fel förblir observerbart via getResult() — du kan använda vilken kanal du vill.

Felkoder

Varje TracioError bär en code av typen TracioErrorCode. Gettern retryable (och hjälpfunktionen isRetryableError()) anger om ett nytt försök kan lyckas.

Code	Betydelse	Retryable
`invalid_config`	Konfigurationen som skickades till `Tracio.init()` är ogiltig	Nej
`multiple_keys`	Mer än en public key användes på samma sida	Nej
`non_browser`	`getResult()` awaitades utanför en webbläsare (t.ex. på servern)	Nej
`load_failed`	Agentskriptet kunde inte laddas	Ja
`blocked`	Skriptet blockerades (annonsblockerare eller CSP)	Ja
`script_error`	Det laddade skriptet kastade ett fel under initieringen	Ja
`network`	Nätverks-/transportfel vid anslutning till API:t	Ja
`timeout`	Anropet överskred den konfigurerade `timeoutMs`-budgeten	Ja
`server`	Edgen/servern returnerade ett upstream-fel	Ja
`destroyed`	Instansen förstördes (via `destroy()`) före anropet	Nej

Terminala koder (invalid_config, multiple_keys, non_browser, destroyed) indikerar ett konfigurations-, användnings- eller livscykelproblem — åtgärda anroparen eller anropa Tracio.init() igen. Retryable-koder är övergående och ett nytt försök kan lyckas.

Strategi för omförsök

För retryable-fel, gör om försöket med backoff mot ett nytt försök istället för att await:a samma avvisade promise igen:

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

Fånga fel

Omslut await tracio.getResult() med try/catch och avgränsa det kastade värdet med isTracioError(), och förgrena sedan på 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)
  }
}

onError-callbacken

Agenten laddas asynkront i bakgrunden. Om laddningen misslyckas innan du någonsin anropar getResult() levereras felet via onError-callbacken. Registrera den direkt efter 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)
})

Samma fel förblir observerbart via getResult() — du kan använda vilken kanal du vill.

Felkoder

Varje TracioError bär en code av typen TracioErrorCode. Gettern retryable (och hjälpfunktionen isRetryableError()) anger om ett nytt försök kan lyckas.

Code

Betydelse

Retryable

invalid_config

Konfigurationen som skickades till Tracio.init() är ogiltig

Nej

multiple_keys

Mer än en public key användes på samma sida

Nej

non_browser

getResult() awaitades utanför en webbläsare (t.ex. på servern)

Nej

load_failed

Agentskriptet kunde inte laddas

blocked

Skriptet blockerades (annonsblockerare eller CSP)

script_error

Det laddade skriptet kastade ett fel under initieringen

network

Nätverks-/transportfel vid anslutning till API:t

timeout

Anropet överskred den konfigurerade timeoutMs-budgeten

server

Edgen/servern returnerade ett upstream-fel

destroyed

Instansen förstördes (via destroy()) före anropet

Nej

Strategi för omförsök

För retryable-fel, gör om försöket med backoff mot ett nytt försök istället för att await:a samma avvisade promise igen:

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