Error Handling

Gérez les erreurs proprement en production pour éviter les échecs silencieux. Lorsqu'un appel tel que getResult() échoue, le SDK lève une TracioError — une sous-classe d'Error dotée d'un champ code lisible par la machine.

Capturer les erreurs

Enveloppez await tracio.getResult() dans un try/catch et affinez la valeur levée avec isTracioError(), puis branchez selon 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)
  }
}

Le callback onError

L'agent se charge de manière asynchrone en arrière-plan. Si le chargement échoue avant que vous n'appeliez getResult(), l'échec est délivré via le callback onError. Enregistrez-le juste après 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)
})

La même erreur reste observable via getResult() — vous pouvez utiliser l'un ou l'autre canal.

Codes d'erreur

Chaque TracioError porte un code de type TracioErrorCode. Le getter retryable (et l'assistant isRetryableError()) indiquent si une nouvelle tentative peut réussir.

Code	Signification	Réessayable
`invalid_config`	La config passée à `Tracio.init()` est invalide	Non
`multiple_keys`	Plus d'une clé publique a été utilisée sur la même page	Non
`non_browser`	`getResult()` a été attendu hors d'un navigateur (p. ex. côté serveur)	Non
`load_failed`	Le script de l'agent n'a pas pu se charger	Oui
`blocked`	Le script a été bloqué (bloqueur de pub ou CSP)	Oui
`script_error`	Le script chargé a levé une erreur lors de l'initialisation	Oui
`network`	Échec réseau/transport pour atteindre l'API	Oui
`timeout`	L'appel a dépassé le budget `timeoutMs` configuré	Oui
`server`	L'edge/serveur a renvoyé un échec en amont	Oui
`destroyed`	L'instance a été détruite (via `destroy()`) avant l'appel	Non

Les codes terminaux (invalid_config, multiple_keys, non_browser, destroyed) indiquent un problème de configuration, d'usage ou de cycle de vie — corrigez l'appelant ou rappelez Tracio.init(). Les codes réessayables sont transitoires et une nouvelle tentative peut réussir.

Stratégie de nouvelle tentative

Pour les erreurs réessayables, relancez avec un backoff sur une nouvelle tentative plutôt que de réattendre la même promesse rejetée :

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

Capturer les erreurs

Enveloppez await tracio.getResult() dans un try/catch et affinez la valeur levée avec isTracioError(), puis branchez selon 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)
  }
}

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

La même erreur reste observable via getResult() — vous pouvez utiliser l'un ou l'autre canal.

Codes d'erreur

Chaque TracioError porte un code de type TracioErrorCode. Le getter retryable (et l'assistant isRetryableError()) indiquent si une nouvelle tentative peut réussir.

Code

Signification

Réessayable

invalid_config

La config passée à Tracio.init() est invalide

Non

multiple_keys

Plus d'une clé publique a été utilisée sur la même page

Non

non_browser

getResult() a été attendu hors d'un navigateur (p. ex. côté serveur)

Non

load_failed

Le script de l'agent n'a pas pu se charger

Oui

blocked

Le script a été bloqué (bloqueur de pub ou CSP)

Oui

script_error

Le script chargé a levé une erreur lors de l'initialisation

Oui

network

Échec réseau/transport pour atteindre l'API

Oui

timeout

L'appel a dépassé le budget timeoutMs configuré

Oui

server

L'edge/serveur a renvoyé un échec en amont

Oui

destroyed

L'instance a été détruite (via destroy()) avant l'appel

Non

Stratégie de nouvelle tentative

Pour les erreurs réessayables, relancez avec un backoff sur une nouvelle tentative plutôt que de réattendre la même promesse rejetée :

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