06Error tracking

Report your own errors

SnowAnalytics catches the errors your visitors hit on its own. Some errors only your code can describe: a payment that was declined, a fallback that kicked in, a failure you handle but still want to see. Send those yourself, the way you send a custom event or identify a user, and say how serious each one is.

In the browser

Call sa.reportError() where you catch the error:

try {
  await chargeCard(order);
} catch (error) {
  sa.reportError(error, { level: "warning", tags: { step: "charge", plan: "pro" } });
}

It takes an Error, or a plain message when there is no error to hand over:

sa.reportError("Coupon service is slow, so the cached price was used", { level: "info" });

The second argument is optional:

Prop

Type

The report travels like any other error: it carries the page, the visitor's browser and device, and the release. On a page that also captures errors on its own, it carries the last 20 things the visitor did too. Email addresses, tokens and long digit runs are removed first, as they are for every error. A page view sends at most 10 of your reports, and the same report is sent once.

Calling the global as a function and the queue form work too, so you can report before sa.js has loaded:

sa("reportError", error, { level: "warning" });

window.snow = window.snow || [];
window.snow.push(["reportError", new Error("Checkout widget failed to load"), { level: "warning" }]);

With and without data-track-errors

With the data-track-errors attribute, the page also reports errors on its own, and your reports join them. Without it, nothing is captured on its own: the error script loads the first time your code calls sa.reportError(), and sends only what you report. With data-track-errors="false", sa.reportError() sends nothing. A visitor who sends Do Not Track or Global Privacy Control, or who has called sa.optout(), reports nothing either way.

From your server

Errors your backend catches go to the same endpoint as server errors: POST /api/v1/errors, with a server key. Add level, handled and tags:

curl -X POST https://api.snowanalytics.app/api/v1/errors \
  -H "Authorization: Bearer $SNOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "node",
    "type": "PaymentDeclined",
    "message": "Card declined by the issuer",
    "level": "warning",
    "handled": true,
    "tags": { "plan": "pro" }
  }'

The errors API lists every field, and Server errors has copy-paste code for Node, Hono and Python.

Levels

A level says how serious the sender thinks an error is:

LevelUse it for
fatalThe page or the process can't go on.
errorSomething broke that you didn't plan for. This is the default, and what SnowAnalytics assigns to everything it captures on its own.
warningSomething went wrong and you recovered: a retry that worked, a fallback.
infoWorth knowing, but not a problem.

On the issue, the header shows a Fatal, Warning or Info badge. An error shows no badge. An issue takes the level its latest event sent.

A level labels an issue. It doesn't change how SnowAnalytics counts or ranks it, or when an alert fires. To keep an error out of your counts, use one of the tools below.

Handled and unhandled

An error is handled when your code caught it, and unhandled when it reached the browser's global handler or took down the process. sa.reportError() marks an error as handled unless you pass handled: false. The errors SnowAnalytics captures in the browser on its own are unhandled. The line above the issue's title says handled or unhandled, taken from the latest event that tells, and says nothing when none does, such as a failed request or a server report without handled.

Keep the noise out

Pick the lightest tool that fits:

  • Send it as a warning or info. It stays visible and is easy to tell from real failures.
  • Ignore it in the browser. An error you report is checked against data-ignore-errors and window.SNOW_IGNORE_ERRORS like any other. A message that matches is never sent.
  • Ignore it from the dashboard. On the issue, open Ignore and choose Every error like this…. The rule applies to errors from the browser and from your server, with no change to your code. See Ignore errors like this.
  • Ignore the issue. Ignore → This issue mutes one issue and keeps its events.

An error you report on purpose is never set aside as coming from a third-party script, even when its stack is all in someone else's file.

On this page