Concepts

Q: Why 202 instead of 200?

Same as HTTP 202 on ingest: non-blocking accept. Treat 202 plus { "id": " " } as success, then open Issues.

Words these docs use for ingest and triage. Skim once after Welcome.

SDK ──(DSN)──► Envelope / Store ──► Event ──► Issue (fingerprint)
                     │
                     └── scoped to a Project under an Organization

What is an organization?

An organization is the tenant. Projects, issues, and settings all sit under it.

Members sign in with email/password or Google OAuth. Dashboard queries use PostgreSQL RLS (app.current_org_id), so you never pass an org id in URLs.

What is a project?

A project is one app or service: frontend, API, worker. It owns DSN keys, retention, and an ingest cap.

Retention is 14 / 30 / 90 days; the default cap is 5000 events/hour. Switching projects changes :projectId in /p/:projectId/…. See Projects.

What is a DSN?

A DSN is the ingest URL for one project. Copy it from Settings → SDK connection.

http://{public_key}@{host}/{dsn_project_id}

Local seed example (numeric path — required by official Sentry SDKs):

http://a1b2c3d4e5f6g7h8i9j0@localhost:8080/100001

Public key: safe in browser bundles
DSN project id: numeric segment in the DSN (internal projects still use UUIDs in dashboard URLs)
Secret: shown once, for server-side and legacy store auth

Ingest routes accept the numeric DSN id or a project UUID (curl/fixtures only; SDKs reject UUID paths).

Revoked keys return 403. DSN keys cannot read issues or fire webhooks.

What is an envelope?

An envelope is POST /api/{project_id}/envelope/ with Content-Type: application/x-sentry-envelope.

POST /api/{project_id}/envelope/
Content-Type: application/x-sentry-envelope

Auth is X-Sentry-Auth or a sentry_key query param. Success is 202 { "id": "<uuid>" }. Legacy store returns the same 202 with JSON (or gzip/zlib). Body cap is 2 MB. Transaction items are discarded; exception events and breadcrumbs are kept.

What is an event?

An event is one occurrence: exception type and value, stack frames, breadcrumbs, tags, optional user.

Events live in monthly partitions. Retention drops old partitions and issue aggregates stay. Dashboard: Events. The HTTP read path needs a session, not a DSN.

What is an issue?

An issue is the group of events that share a fingerprint. The Issues list is the dashboard home.

The default fingerprint is SHA-256 of normalized exception type plus the top in-app stack frame (file + function + line). A custom fingerprint array on the event overrides it. See Issues.

Events that share a fingerprint:

Normalized exception type (or message)
Top in-app stack frame (file + function + line)

What are environment and release tags?

environment and release are event tags you set in Sentry.init. They are not credentials.

Tag	Role
`environment`	Header filter: `production`, `staging`, `local`
`release`	Version string; used for regressions and sourcemap match

What is the spike valve?

A per-fingerprint token bucket, about 100 raw events per minute.

When saturated, Epure still returns 202 and increments the counter, but drops duplicate bodies. The hourly project cap is separate: default 5000 events/hour, then 403 ingest_cap_exceeded. Details: API errors.

FAQ

Is a DSN the same as a session cookie?

No. The DSN authenticates ingest (`/envelope/`, `/store/`, release files, user feedback). Issues, Events, and other `/api/v1/*` routes need a login cookie. Agent automation uses a separate PAT on `/api/v1/agent/*`. DSN headers on dashboard APIs return **401**. Full table: [Authentication](/docs/api/authentication).

What does HTTP 202 mean on ingest?

**202 Accepted** means the DSN and body passed the gate. Persist and JS/TS demangle run on a Tokio queue after the response. A 202 can still yield an empty Issues list when the environment filter is wrong. See [Verify](/docs/get-started/verify).

What is the 2 MB cap and the spike valve?

Ingest bodies over **2 MB** return **413** `payload_too_large`. The spike valve is about **100** raw events per minute per fingerprint; saturated fingerprints still get **202** and a counter bump. The hourly project cap (default **5000**) returns **403**. See [API errors](/docs/api/errors).

Why 202 instead of 200?

Same as HTTP 202 on ingest: non-blocking accept. Treat 202 plus { "id": "<uuid>" } as success, then open Issues.

How does grouping work?

Default grouping is SHA-256 of normalized exception type plus the sanitized top in-app frame. Same type and frame land on one issue and the count goes up. An SDK fingerprint overrides it. Merge and split handle stacks that share a cause but differ slightly: Issues.