Handle SDK errors

Find out why an event was not sent, and what the SDK did about it.

The SDK never breaks your site: no method throws, and its promises never fail. When an event cannot be sent, the SDK calls your onError function with the reason.

Get the errors

src/loomduct.ts

import { Loomduct } from '@loomduct/js'
import { webAnalytics } from '@loomduct/js/web-analytics'

export const loomduct = new Loomduct({
  token: 'lmt_your_project_token',
  plugins: [webAnalytics()],
  onError: (error) => {
    console.warn(error.code, error.message)
  },
})

Each error has a code, a message, and for most codes the event. New codes can come in later versions, so if you switch on code, keep a default branch.

Error codes

`code`	What happened	What the SDK does
`network`	No network, the request was blocked (for example by an ad blocker), or it timed out	Retries twice, after about 1 and 3 seconds, then drops the event.
`server`	A temporary server error (`500`, `503`) or too many requests (`429`)	Retries twice, after about 1 and 3 seconds, then drops the event.
`rate_limited`	Your code sent more than 10 events per second (bursts up to 100)	Drops the extra events.
`invalid_event`	The event broke a rule for names and properties (`400`)	Drops the event. No retry.
`invalid_token`	The project token is wrong (`401`)	Logs one error and stops sending for this page load.
`too_large`	The event is larger than 32 KB (`413`)	Drops the event. No retry.
`plugin`	A plugin failed to start, or its code failed to load	Turns that plugin off for this page load. Everything else keeps working.
`before_send`	Your `beforeSend` function threw	Drops the event, so data you meant to remove is never sent.

Good to know:

Retries never create duplicates: Loomduct stores each event only once.
Events that wait for a retry live in memory only. If the visitor closes the page first, they are lost.
Events sent when a page closes ($pageleave, $web_vitals) use sendBeacon. The browser does not report if those fail, so they never reach onError.

See errors while you build

In development builds, the SDK logs every error in the browser console with the prefix [loomduct], and warns about mistakes before sending, like an event name that starts with $ or a property that is an object.