Server-side errors

POST https://api.snowanalytics.app/api/v1/errors

Send errors from your backend to SnowAnalytics, where they appear in Errors → Issues beside the ones your visitors hit in the browser. Server errors has copy-paste code for Node, Hono and Python, and any other language calls it the same way. Authenticated with a server key.

Authentication

Authorization: Bearer snw_live_your_key

The key needs the events:write scope, which every server key has. A read key can't send errors.

Request body

Send one event as a JSON object, or up to 50 as a JSON array. The body can be up to 2 MB.

FieldTypeNotes
messagestringRequired. Up to 2,000 characters.
platformstringRequired. node, bun, deno, workerd or python.
typestringThe error's class, such as TypeError. Defaults to Error.
levelstringerror (default), fatal, warning or info. The issue shows a badge for anything but error.
handledbooleantrue when your code caught the error, false when it went uncaught, such as one you report from uncaughtException. The issue shows which. Leave it out when you don't know.
timestampstring | numberISO 8601 or Unix milliseconds. Defaults to now. One more than 5 minutes ahead or 90 days behind is recorded as now.
eventIdstringA UUID you choose. A batch you send again, because a reply was lost, isn't counted twice.
stackstringThe stack as your runtime printed it: error.stack, or a Python traceback. SnowAnalytics reads the frames out of it when you send no frames. Up to 16,000 characters.
framesarrayThe stack as frames, top frame first, if you parse it yourself. See below.
releasestringYour build or version. Up to 64 characters.
environmentstringproduction, staging and so on.
runtimestringThe runtime's version, such as 22.4.0.
requestobjectmethod, path (without a query string) and status.
userobject{ "id": "user_12345" }. The ID you give sa.identify(). See below.
tagsobjectUp to 20 tags, with keys of letters, numbers and _ . : -, and text, number or boolean values.
breadcrumbsarrayThe last 20 things that happened: { at, type, text, status?, ms? } with type of console, network, click or navigation and at in Unix milliseconds.

Text and lists beyond their limits are cut, not refused, so one big report doesn't lose a batch. Frames are kept to 100 and breadcrumbs to 20. A list of more than 200 is refused.

Frames

Each frame is { function, file, line, col, inApp, context? }.

  • file is relative to your project root for your own code, so a build in another folder is the same issue.
  • inApp marks your code. Files under node_modules or site-packages, and the runtime's own, are never counted as yours, whatever you send.
  • context is the source around the frame, { "start": 40, "lines": ["…", "…"] }, where lines[0] is line start. Up to seven lines. Send it for your own frames.

SnowAnalytics groups errors into issues by their type, their message without the parts that change (numbers, quoted values, IDs) and the file of the top frame of your own code.

Users

When user.id is a user you identified in the browser with sa.identify(), the error is tied to that person's most recent visitor and counts under People. Otherwise it counts no one.

Example

curl -X POST https://api.snowanalytics.app/api/v1/errors \
  -H "Authorization: Bearer snw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '[{
    "type": "TypeError",
    "message": "Cannot read properties of undefined (reading '\''id'\'')",
    "platform": "node",
    "runtime": "22.4.0",
    "release": "1.4.2",
    "environment": "production",
    "request": { "method": "GET", "path": "/orders/:id", "status": 500 },
    "frames": [
      { "function": "getOrder", "file": "src/orders.ts", "line": 42, "col": 9, "inApp": true }
    ]
  }]'

Responses

StatusBodyMeaning
202 Accepted{ "status": "success", "data": { "accepted": 1, "duplicates": 0 } }The errors are queued. duplicates counts those skipped for a repeated eventId.
400 Bad Request{ "status": "error", "error": { "code": 400, "message": … } }Invalid JSON, or an event with a missing or invalid field. The message names it, like Invalid event at 0.platform. A batch is all or nothing.
401 Unauthorized{ "status": "error", "error": { … } }Missing or invalid API key.
403 Forbidden{ "status": "error", "error": { … } }The key lacks the events:write scope.
413 Payload Too Large{ "status": "error", "error": { … } }The body is over 2 MB.
423 Locked{ "status": "error", "error": { … } }The workspace's trial ended without a plan, so tracking is paused.
429 Too Many Requests{ "status": "error", "error": { … } }More than 120 requests a minute for this key. The reply carries Retry-After: 30.
503 Service Unavailable{ "status": "error", "error": { … } }The errors couldn't be queued. Retry shortly: the reply carries Retry-After: 30.

Retry on 429 and 503, with a growing wait. The other errors won't change on a retry.

On this page