Error Handling

Behandeln Sie Fehler in der Produktion sauber, um stille Ausfälle zu vermeiden. Wenn ein Aufruf wie getResult() fehlschlägt, wirft das SDK einen TracioError — eine Error-Unterklasse mit einem maschinenlesbaren code-Feld.

Fehler abfangen

Umschließen Sie await tracio.getResult() mit try/catch und grenzen Sie den geworfenen Wert mit isTracioError() ein, dann verzweigen Sie über 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)
  }
}

Der onError-Callback

Der Agent lädt asynchron im Hintergrund. Wenn das Laden fehlschlägt, bevor Sie jemals getResult() aufrufen, wird der Fehler über den onError-Callback zugestellt. Registrieren Sie ihn direkt nach 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)
})

Derselbe Fehler bleibt über getResult() beobachtbar — Sie können beide Kanäle nutzen.

Fehlercodes

Jeder TracioError trägt einen code vom Typ TracioErrorCode. Der retryable-Getter (und die Hilfsfunktion isRetryableError()) geben an, ob ein erneuter Versuch erfolgreich sein könnte.

Code	Bedeutung	Retryable
`invalid_config`	Die an `Tracio.init()` übergebene Konfiguration ist ungültig	Nein
`multiple_keys`	Mehr als ein Public Key wurde auf derselben Seite verwendet	Nein
`non_browser`	`getResult()` wurde außerhalb eines Browsers awaited (z. B. auf dem Server)	Nein
`load_failed`	Das Agenten-Skript konnte nicht geladen werden	Ja
`blocked`	Das Skript wurde blockiert (Ad-Blocker oder CSP)	Ja
`script_error`	Das geladene Skript hat beim Initialisieren einen Fehler geworfen	Ja
`network`	Netzwerk-/Transportfehler beim Erreichen der API	Ja
`timeout`	Der Aufruf hat das konfigurierte `timeoutMs`-Budget überschritten	Ja
`server`	Die Edge/der Server gab einen Upstream-Fehler zurück	Ja
`destroyed`	Die Instanz wurde vor dem Aufruf zerstört (über `destroy()`)	Nein

Terminale Codes (invalid_config, multiple_keys, non_browser, destroyed) deuten auf ein Konfigurations-, Nutzungs- oder Lebenszyklusproblem hin — beheben Sie den Aufrufer oder rufen Sie Tracio.init() erneut auf. Retryable-Codes sind vorübergehend, und ein erneuter Versuch könnte erfolgreich sein.

Retry-Strategie

Wiederholen Sie bei retryable Fehlern mit Backoff über einen frischen Versuch, statt dasselbe abgelehnte Promise erneut zu 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))
    }
  }
}

Fehler abfangen

Umschließen Sie await tracio.getResult() mit try/catch und grenzen Sie den geworfenen Wert mit isTracioError() ein, dann verzweigen Sie über 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)
  }
}

Der onError-Callback

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

Derselbe Fehler bleibt über getResult() beobachtbar — Sie können beide Kanäle nutzen.

Fehlercodes

Jeder TracioError trägt einen code vom Typ TracioErrorCode. Der retryable-Getter (und die Hilfsfunktion isRetryableError()) geben an, ob ein erneuter Versuch erfolgreich sein könnte.

Code

Bedeutung

Retryable

invalid_config

Die an Tracio.init() übergebene Konfiguration ist ungültig

Nein

multiple_keys

Mehr als ein Public Key wurde auf derselben Seite verwendet

Nein

non_browser

getResult() wurde außerhalb eines Browsers awaited (z. B. auf dem Server)

Nein

load_failed

Das Agenten-Skript konnte nicht geladen werden

blocked

Das Skript wurde blockiert (Ad-Blocker oder CSP)

script_error

Das geladene Skript hat beim Initialisieren einen Fehler geworfen

network

Netzwerk-/Transportfehler beim Erreichen der API

timeout

Der Aufruf hat das konfigurierte timeoutMs-Budget überschritten

server

Die Edge/der Server gab einen Upstream-Fehler zurück

destroyed

Die Instanz wurde vor dem Aufruf zerstört (über destroy())

Nein

Retry-Strategie

Wiederholen Sie bei retryable Fehlern mit Backoff über einen frischen Versuch, statt dasselbe abgelehnte Promise erneut zu 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))
    }
  }
}