Server errors

The tracking snippet sees what happens in the browser. Your server sees the rest: the route that throws, the job that fails. Send those errors to POST /api/v1/errors with a server key and they land in Errors → Issues beside the browser's, ranked the same way. Without a package, it is one request per error.

On Node.js, Bun or Deno, the package for servers and APIs does all of this for you, with handlers for Express, Hono, Fastify and Koa. On Next.js, the SnowAnalytics package reports server errors from Server Components, route handlers, server actions and the proxy, and has captureException and cron.wrap for your own code.

Connect a server

Make a server key

Open Site settings → API keys and create a server key. Put it in an environment variable such as SNOW_API_KEY. The same key sends cron check-ins.

Add the reporter

Copy the code for your server below. Errors → Set up → Server has the same code with your site's address filled in.

Throw something

The first error shows up in Errors within seconds.

The code

Each example sends the error's type, message and stack. SnowAnalytics reads the frames out of the stack, so an issue shows the file and line it broke on.

Node 18 and later, Bun and Deno have fetch. Set platform to bun or deno there.

export function reportError(error, request) {
  return fetch("https://api.snowanalytics.app/api/v1/errors", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SNOW_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      platform: "node",
      type: error?.name,
      message: String(error?.message ?? error),
      stack: error?.stack,
      request,
    }),
  }).catch(() => {});
}

process.on("unhandledRejection", (reason) => reportError(reason));
process.on("uncaughtException", (error) => {
  reportError(error).finally(() => process.exit(1));
});

Call reportError(error) in your own catch blocks too, for errors you handle but still want to see.

What else to send

Add any of these to the body. See the API reference for all of them.

  • level (fatal, error, warning or info) and handled (false for an error that crashed the request or the process, such as one reported from uncaughtException), so an issue shows how serious it is and whether your code caught it. See Report your own errors.
  • release and environment, so a regression shows which release brought it.
  • request: { "method": "GET", "path": "/orders/:id", "status": 500 }. Send the route pattern, not the real path.
  • user: { "id": "user_12345" }, the ID you give sa.identify(), so the error counts that person under People.
  • eventId, a UUID you choose, so a request you send again after a timeout isn't counted twice.

Errors from your server are not tied to a browser visit unless you send user.

On this page