Server-side errors
POST https://api.snowanalytics.app/api/v1/errorsSend 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_keyThe 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.
| Field | Type | Notes |
|---|---|---|
message | string | Required. Up to 2,000 characters. |
platform | string | Required. node, bun, deno, workerd or python. |
type | string | The error's class, such as TypeError. Defaults to Error. |
level | string | error (default), fatal, warning or info. The issue shows a badge for anything but error. |
handled | boolean | true 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. |
timestamp | string | number | ISO 8601 or Unix milliseconds. Defaults to now. One more than 5 minutes ahead or 90 days behind is recorded as now. |
eventId | string | A UUID you choose. A batch you send again, because a reply was lost, isn't counted twice. |
stack | string | The 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. |
frames | array | The stack as frames, top frame first, if you parse it yourself. See below. |
release | string | Your build or version. Up to 64 characters. |
environment | string | production, staging and so on. |
runtime | string | The runtime's version, such as 22.4.0. |
request | object | method, path (without a query string) and status. |
user | object | { "id": "user_12345" }. The ID you give sa.identify(). See below. |
tags | object | Up to 20 tags, with keys of letters, numbers and _ . : -, and text, number or boolean values. |
breadcrumbs | array | The 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? }.
fileis relative to your project root for your own code, so a build in another folder is the same issue.inAppmarks your code. Files undernode_modulesorsite-packages, and the runtime's own, are never counted as yours, whatever you send.contextis the source around the frame,{ "start": 40, "lines": ["…", "…"] }, wherelines[0]is linestart. 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
| Status | Body | Meaning |
|---|---|---|
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.