HTTP Reporting

Quick Reference#

The provider registers the interceptor for you. Nothing to call:

Status	What Sentry gets
0 (no response: timeout, refused connection, CORS rejection on web)	An event
500 and above	An event
Anything else, such as 401, 404, 422, 429	A warning breadcrumb on whatever fails next

Why It Exists#

Magic's Http facade never throws. Every call returns a MagicResponse and the caller reads response.successful, so a failure is a value, not an exception. A global error handler sees none of them, and an app's own habit is usually to log the failure and return. Without this interceptor Sentry would report almost nothing about the surface that breaks most.

The interceptor only reports. It returns the MagicError it was given, so observability can never change the outcome of a request.

Events and Breadcrumbs#

A 4xx is usually the product working: 401 is an expired session, 422 a form filled in wrong, 404 a record someone deleted. Filing those as issues turns the inbox into one nobody opens, so they become breadcrumbs that give context to the next real failure.

An event carries:

Field	Value
Level and logger	error, http
Message	METHOD endpoint failed with STATUS
Fingerprint	['http', method, endpoint, 'STATUS']
Context http_failure	method, endpoint, status_code, and transport_message when there is one

There is no request body and no header in it. An app that turns sendDefaultPii on opts into that risk itself.

Grouping#

The fingerprint carries a normalised endpoint, because a raw path holds a record id and would open one issue per record. SentryNetworkInterceptor.normalizeEndpoint drops the query and turns a numeric or UUID segment into {id}, so /monitors/42/checks and /monitors/43/checks are one issue. The status comes last in the fingerprint, which keeps one endpoint's 500 and 502 apart: they usually have different causes.

The endpoint and fingerprint of a failed HTTP call go through SentryTokenScrubber.scrubApiUrl (a breadcrumb or span URL keeps its ids and query and is only masked), which masks query values and route-bound tokens first, then runs normalizeEndpoint, and last masks any other opaque segment, so a failed invitation call groups under /api/v1/invitations/{token}/accept instead of carrying the token, provided the token is 32 or more [A-Za-z0-9_-] characters. A route rule such as /invitations/:token/accept matches a path that starts at the route, not one behind an /api prefix, so a shorter token in an API path is not masked.

Repeats#

One event per distinct METHOD endpoint status per session; the next occurrence becomes an error breadcrumb marked (repeat). Without that, a client polling a dead endpoint is a flood source: a one-hour outage across a few hundred open tabs is tens of thousands of identical events, and most Sentry plans bill by event count. The repeat breadcrumbs still show the retry pattern to whoever opens the issue.

The set is SentryNetworkInterceptor.reportedFailures. It is process-wide and not time-windowed: a web session is a tab, so it ends with the page, and a returning user reports the failure again.

Double Reporting#

sentry_dio can capture failed requests on its own. The provider turns that off (captureFailedRequests: false) for two reasons: its events are raised inside the SDK adapter, so their stack trace points at the SDK instead of your call site, and they cannot carry the endpoint fingerprint above. Leaving it on would also report every failure twice. The provider still adds sentry_dio's addSentry(), which contributes an HTTP breadcrumb and a span per request.

Gotchas#

Mistake	Fix
Turning captureFailedRequests back on in your own Dio setup	Leave it off; SentryNetworkInterceptor is the one layer that decides event or breadcrumb
Expecting a 404 or 422 to open an issue	They are breadcrumbs by design; look at the breadcrumbs of the next event
Expecting every failed call to arrive as an event	Only the first of a repeated failure per session does; the rest are (repeat) breadcrumbs
Calling normalizeEndpoint to make a URL safe to send	It collapses ids only and a token in the path survives it; use SentryTokenScrubber.scrubApiUrl

Related Documentation#

• Boot and the Provider: where the interceptor is wired.
• Token Scrubbing: the masking scrubApiUrl applies.
• Testing: clearing reportedFailures between tests.