# Error capture

An SDK with error capture reports what goes wrong in a running game on its own: uncaught errors, failed requests, console errors and clicks that did nothing. Each one is an ordinary [typed error event](https://ravensight.io/docs/dashboard/#typed-events), scrubbed, grouped by fingerprint and counted on the event meter like any other event.

## The event

A captured error is an event named `error` by default (any name an allowlist could hold works) with `rs_kind: "error"` and these top-level keys. Only the top level is read.

| Key | Value |
| --- | --- |
| `rs_severity` | `debug`, `info`, `warning`, `error` or `critical` |
| `rs_message` | Required. Stored up to 200 characters, scrubbed. |
| `rs_stack` | Optional. Stored up to 2,000 characters, scrubbed. |
| `rs_source` | Where it came from: `manual` (or absent) for an error your code reports, or `uncaught`, `unhandled_rejection`, `request`, `console`, `log`, `dead_click` or `crash` for automatic capture. Any other value breaks the contract. |
| `rs_error_type` | Optional. The error's class or type, such as `TypeError`. Stored up to 100 characters. |
| `rs_trail` | Optional, one string. Up to 20 log lines before the error, oldest first, joined by a line break, stored up to 1,500 characters, scrubbed. Kept only while the game's trail switch is on. |
| `rs_fp` | Written by the server: the error's fingerprint, `v1:` and 16 hex characters. One your game sends is removed. |

A failed request's message is the method, the host, the path with its identifiers replaced by `:id`, and the status or `network`, for example `POST api.example.com/v1/kickoff/:id 500`. It never carries a query string, a fragment, a header or a body. A dead click's message is the control's role and name, such as `Dead click: button Kick Off`.

## What is removed before it is stored

The SDK scrubs the message, stack and trail on the device, and the server scrubs them again before storing them. Error text is scrubbed once more whenever it is shown or returned (the Errors view, `get_health`, `list_error_issues` and `get_error_issue`), so errors stored under an older rule are covered too.

- Email addresses become `[email]`.
- Bearer tokens, token-shaped strings, Ravensight keys (`gt_`) and long random strings that contain a digit become `[token]`. A file path keeps its shape.
- IPv4 and IPv6 addresses become `[ip]`.
- A home folder (`/Users/name`, `/home/name`, `C:\Users\name`, `C:\Documents and Settings\name`, either slash) becomes `~`. The name is the whole folder, spaces included, so `C:\Users\Jo Ann\game` becomes `~\game`.
- A web address loses its query, its fragment and any user name and password.

## How errors are grouped

The fingerprint is built from the source, the error type, the message with numbers, ids, quoted text and web addresses replaced, and the file of the first frame in the stack that is your game's code (frames from the engine, the browser and the Ravensight SDK are skipped, as are line numbers and build hashes). On a native build the function name counts as well; on the web it does not, because shipped web code is usually minified. Two errors that differ only in an id or a number are one group on purpose.

## Resolving and regressions

Resolve an issue with the build the fix shipped in, **Fixed in build** in the Errors view (`build` on `POST /api/v1/games/:gameId/errors/:id/status`). The issue opens again, marked Regressed, when it is seen after the resolve on that build or a later one. A build older than the fix is a player who has not updated yet, and never reopens it. Every build seen since the resolve is checked, not only the latest. Builds compare as numbers part by part (`1.10` is later than `1.9`), a leading `v` is ignored, and a pre-release such as `1.3-beta` comes before `1.3`. With no build named, only a build later than the last one the issue was seen in reopens it. A build that is not a number, such as a commit hash, has no order, so any other build reopens it.

## Owner, priority, notes and the triage log

Each issue can have one owner and a priority. Set either or both with `POST /api/v1/games/:gameId/errors/:id/triage`, sending the `revision` you read plus `assigneeId` (a member of your studio, or `null` to clear it) and `priority` (`none`, `low`, `medium`, `high` or `urgent`). It answers `{ issue }` with the new revision. A request that changes nothing leaves the revision where it was. The refusals are `400 invalid_revision`, `400 nothing_to_change`, `400 invalid_priority`, `400 invalid_assignee` for anyone who is not a member of the studio, and `409 revision_conflict` when someone else changed the issue first.

`POST /api/v1/games/:gameId/errors/:id/notes` with `{ text }` (1 to 1,000 characters) adds a note to the issue and answers `201 { entry }`. A note does not move the revision. It is refused with `400 invalid_note`, or `409 history_full` once an issue holds 500 steps.

`GET /api/v1/games/:gameId/errors/activity` is the triage log: every step on every issue of the game, newest first, as `{ entries, nextBefore }`. Each entry names the issue, the step, when it happened and who did it. Page with `limit` (1 to 100, 50 by default) and `before`, passing back the `nextBefore` you were given without reading into it. `action` narrows the log to one step: `note`, `open`, `resolved`, `ignored`, `assigned` or `priority`. An unknown step is `400 invalid_action` and a cursor that was not returned by the log is `400 invalid_cursor`. Writing needs a role that can edit the studio; reading needs one that can read the game.

A studio you share a game with reads its error issues but not your triage: no resolved or regressed dates, no fixed-in build, no owner, no priority, no notes and no history, and its triage log is empty.

## What happened around an error

An issue's details in the Errors view (and `GET /api/v1/games/:gameId/errors/:id`) add three things for your own studio.

- **Players who came back.** Of the devices that hit the error, the share that did not start another session within 7 days, beside the same share for devices that played in the same days and did not hit it. Each device is counted from its first time hitting the error, or from its first event for the others. It reads only days at least 7 days old, so every device had the whole 7 days: pick the last 30 days to see it. This is correlation, never cause. A higher share means players who hit this error returned less often, not that the error made them leave. Playtest and doctor sessions are never counted.
- **Breadcrumbs.** For each recent example, the last 20 events of the same session before the error: the event name, its level, its kind (one of the typed kinds, or other) and how long before the error it happened. Never a property value.
- **The log trail.** The `rs_trail` the device sent with each example, scrubbed again when it is read and cut to 1,500 characters, shown only while the game's trail switch is on. It is text from players' devices and is marked that way.

A studio you share a game with gets none of these three. The `get_error_issue` tool returns them as `playersLost`, `breadcrumbs` and `trail`, and `get_health` lists the five biggest open issues and, for each top message, its builds with exact counts, newest build first.

## The two switches

Each game has two switches in its environment card in Settings, also settable with `PATCH /api/v1/games/:gameId` as `errorCaptureEnabled` and `errorTrailEnabled` (owners and admins).

| Switch | Default | What it does |
| --- | --- | --- |
| Capture errors automatically | On | Off: the SDK installs no hooks, and the server drops any error whose `rs_source` is automatic before it is counted, free, as `error_capture_disabled` on the Implementation health card. Errors your code reports with `rs_source: "manual"` or no source always arrive. |
| Send a log trail with each error | Off | On: a captured error carries its last log lines as `rs_trail`. Off: the server removes any `rs_trail` it receives. |

The SDKs read both from the session answer (`POST /api/v1/session`) and from `GET /api/v1/settings` as `"errorCapture": { "enabled": true, "trail": false }`. The server applies them as well, so a build that read its settings before you changed them still stops being charged for automatic errors.

## Limits on the device

- Nothing is installed without a key, before the player's consent where your game asks for it, or while capture is off.
- A session sends at most 30 captured errors, at most 3 of the same error, at most 10 with a trail, and at most 6 a minute. Past those they are dropped on the device, silently.
- The hooks pass every error on to whatever handled it before, and never capture the SDK's own requests or log lines.
- With a [public key](https://ravensight.io/docs/public-builds/), `capture_errors` lets error events past the allowlist with room for the message, stack and trail.

## What it costs

One captured error is one event on the shared event meter, the same as any other event: it uses the included monthly events first, then the prepaid balance at the ordinary event rate (see [usage, billing and limits](https://ravensight.io/docs/limits/)). The trail adds nothing. A dropped error, on the device or on the server, costs nothing. There is no separate rate and no cap of its own; the device limits above are what bound it.

## Error text and the analyst

Error messages, issue titles, build versions, breadcrumb names and trails are written on players' devices, so Huginn and the Analytics MCP tools receive them marked as player text, a message cut to 200 characters, an issue title to 120 and a version to 100, to be read as evidence and never followed as instructions.

Source: https://ravensight.io/docs/error-capture/
Last updated: 2026-11-15
