---
title: "List grouped error fingerprints with a release-baselined verdict"
method: GET
path: "/projects/v1/{project_id}/errors"
tags: ["Projects"]
---

# List grouped error fingerprints with a release-baselined verdict

`GET /projects/v1/{project_id}/errors`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/projects/v1/{project_id}/errors`
- Auth: one of:
  - API key in header `apikey`
  - HTTP bearer

The platform's durable error memory: uncaught throws, boot crashes (init crash-loops that never produce an app log line), invoke-level failures (throttle exhaustion, payload caps), and coarse handled-5xx — grouped by deploy-stable fingerprint and attributed to the release each identity was first seen under. The response LEADS with a computed `verdict` (new/recurring counts vs the baseline release, invocation volume, fidelity coverage). `new_in=<release_id|active>` is the promote-gate query: `run402 errors list --new-in <release_id> --watch 10m --fail-on-new` exits 0 when no new identities appeared. Platform traffic-shaping denials (rate limits, auth gates) are never counted as app errors. Auth: the project's own apikey OR a GitHub-OIDC CI session bearer for its own bound project (a deliberate, scoped v1.36 widening — a CI session already has deploy authority, so reading the resulting fingerprints is strictly less power and makes the promote gate keyless). Read-only, own-project-only; a CI session bound to a different project gets 403, a revoked binding 401.

## Path parameters

- `project_id` string, required: Run402 project ID. Public IDs are not UUIDs.

## Query parameters

- `since` string, date-time
- `until` string, date-time
- `function` string
- `kind` 'uncaught' | 'boot_crash' | 'invoke_failed' | 'handled_5xx'
- `fingerprint` string
- `new_in` string
- `limit` integer
- `cursor` string

## Response `200`

Verdict + grouped error identities (newest activity first)

- object
  - `verdict` ErrorsVerdict, required: The computed promote-vs-revert predicate, returned FIRST. Pairs fingerprint counts with real traffic volume so zero errors over zero traffic is a shrug, not health.
    - `window` object
      - `since` string, date-time
      - `until` string, date-time
    - `compared_release_id` unknown
    - `baseline_release_id` unknown
    - `new_fingerprints` integer
    - `recurring_fingerprints` integer
    - `invocations_in_window` integer: Function invocations observed in the window (hourly metering buckets).
    - `coverage` object: Which functions fingerprint at full fidelity vs coarsely (pre-side-channel bundles; redeploy upgrades them).
      - `full_fidelity_functions` integer
      - `coarse_functions` integer
    - `row_cap` object: Per-project fingerprint row bound. When `at_cap` is true, oldest-idle rows are being evicted and very-stale identities may be missing.
      - `limit` integer
      - `at_cap` boolean
  - `errors` ErrorFingerprint[], required
    - `fingerprint_id` string: Stable identity id (`fp_…`). Deploy-stable: computed from normalized message + stable frame NAMES, never line/column numbers.
    - `function` string
    - `kind` 'uncaught' | 'boot_crash' | 'invoke_failed' | 'handled_5xx'
    - `fingerprint_quality` 'frame_names' | 'message_only' | 'coarse': Honest-degradation tier. `coarse` means the function predates the error side-channel — redeploying it upgrades future fidelity.
    - `error_name` string: Builtin JS error name, `CustomError`, a Lambda error type (e.g. `Runtime.UserCodeSyntaxError`), or `HTTP_<status>` for coarse rows.
    - `message_template` string: Normalized first-line message (trace ids/UUIDs/tokens replaced by placeholders; short quoted identifiers like PG relation names kept).
    - `stable_frames` string[]
    - `count` integer
    - `first_seen` string, date-time
    - `last_seen` string, date-time
    - `first_seen_release_id` unknown
    - `last_seen_release_id` unknown
    - `samples` object: The pinned first occurrence (kept for the row's lifetime — diagnostic gold after logs expire) plus a newest-wins ring of up to 10 recent occurrences.
      - `first` object
      - `recent` object[]
    - `next_actions` object[]: Runnable logs drill-down commands for sample request/attempt ids (function-diagnostics surface).
  - `has_more` boolean, required
  - `next_cursor` string

## Other responses

- `401`: Missing or invalid authentication. Run402-originated JSON bodies use the canonical ErrorEnvelope.
- `403`: Key does not belong to the addressed project (FORBIDDEN)

---

[API](https://skmtc.dev/run402/apis/run402-api.md) · [All operations](https://skmtc.dev/run402/apis/run402-api/llms.txt) · [OpenAPI document](https://skmtc.dev/run402/apis/run402-api/revisions/893607557f50?raw)