Short answer: send a small, versioned React error-boundary event to a same-origin backend API with fetch, acknowledge it quickly, and page only when those events correlate with a measurable checkout failure; this gives a marketplace team useful error tracking without an SDK while keeping rollback independent from the telemetry path.
The decisive trade-off is delivery confidence versus checkout isolation. A browser report is best effort, so it can be lost during navigation or network failure, but making checkout wait for telemetry turns an observer into a production dependency. I've been woken by alerts that meant nothing and missed the one that mattered. That experience leaves me skeptical of any design whose main artifact is a dashboard rather than a precise answer to two questions: what page fired, and can we roll back the responsible release without losing the evidence?
Do not block the buyer.
What the incident should teach us
Consider a bounded failure during the marketplace payment-review step. Release web-2026.08.19.3 changes how a cart promotion is rendered. A particular cart state throws during rendering, the error boundary replaces the broken subtree, and the buyer never reaches the final confirmation control. Server request logs still show successful page and cart reads. A server-only alert therefore has no direct signal for the failed render, while a raw count of JavaScript exceptions cannot tell the responder whether revenue flow is affected.
The useful invariant is narrower: a client exception becomes operational evidence only after it is tied to a workflow stage, a release, and a stable error fingerprint. The event needs no buyer name, email, address, card data, access token, full URL query string, or arbitrary component state. It needs enough context to distinguish payment_review on the marketplace checkout route from a harmless exception on a seller profile, and enough release context to support a rollback decision. This is an observability event, not a browser memory dump.
That distinction changes the alert. Page on the rate of distinct checkout attempts producing the same fingerprint after a release, preferably alongside an independent business signal such as a drop in checkout completion. Do not page on every event. A single browser can retry, extensions can inject scripts, and one defect can produce a cascade of component errors. The receiver should preserve the event stream, but the paging rule should aggregate it.
The event stream also belongs outside the application's local filesystem. The Twelve-Factor logs guidance treats logs as event streams and leaves routing and storage to the execution environment. A browser intake is not stdout, of course, but the same separation of concerns applies: accept a structured event, append or forward it, and let downstream systems index, retain, and aggregate it. The intake request should not synchronously perform symbolication, enrichment, notification, or a database report query.
How should a React error boundary fetch JavaScript failures to a backend API?
Use an explicit event contract and keep the boundary's failure path boring. The example below is a Go source file that embeds the React source served by the application; the embedded component catches its descendant render error, builds an allowlisted payload, and sends it without awaiting the response. The error message is capped, the stack is omitted because it may contain data the intake policy has not approved, and a random event ID lets the receiver make retry handling idempotent.
package webassets
const CheckoutBoundarySource = `
class CheckoutBoundary extends React.Component {
constructor(props) {
super(props);
this.state = { failed: false };
}
static getDerivedStateFromError() {
return { failed: true };
}
componentDidCatch(error, info) {
const report = {
schema_version: 1,
event_id: crypto.randomUUID(),
occurred_at: new Date().toISOString(),
release: window.__APP_RELEASE__,
route: "/checkout/review",
workflow_stage: "payment_review",
error_name: String(error?.name || "Error").slice(0, 80),
error_message: String(error?.message || "Unknown error").slice(0, 240),
component_fingerprint: stableComponentFingerprint(info.componentStack),
};
void fetch("/api/client-errors", {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: "same-origin",
keepalive: true,
body: JSON.stringify(report),
}).catch(() => {});
}
render() {
if (this.state.failed) {
return <CheckoutRecovery />;
}
return this.props.children;
}
}
`
stableComponentFingerprint should be an application-owned function with deterministic output, not a pass-through for the entire component stack. For example, it can map an allowlisted sequence of component names to a digest. The backend can then group identical failures without receiving verbose browser internals. I'm not sure one fingerprint rule will work across every build pipeline; source transformations and minification differ, so settle that rule with a fixture generated by the exact production build and keep the fixture in release tests.
The empty catch is deliberate. It does not claim delivery succeeded, and it prevents a telemetry rejection from creating another user-visible failure. keepalive improves the shape of a short request near navigation, but it does not turn browser delivery into a durable queue. If durable capture is a legal or financial requirement, client-side fetch alone is the wrong mechanism; record the authoritative state transition on the server.
One more boundary matters: an error boundary covers the React tree below it. Failures in event handlers and asynchronous work need explicit capture at the place where that work is executed. Route those failures through the same schema rather than installing a broad handler that uploads every value attached to a global error.
Keep the receiver dull and rollback-safe
The backend has four jobs: constrain the request, authenticate it with the browser session and origin policy already used by the site, deduplicate the event ID, and append the accepted record to the normal observability stream. It should return before expensive processing. This Go handler shows the shape, including strict JSON decoding and size limits; EventSink is intentionally generic so the same contract can write to a bounded queue, a log appender, or another internal transport.
package clienterrors
import (
"encoding/json"
"errors"
"io"
"net/http"
"strings"
"time"
)
type Event struct {
SchemaVersion int `json:"schema_version"`
EventID string `json:"event_id"`
OccurredAt time.Time `json:"occurred_at"`
Release string `json:"release"`
Route string `json:"route"`
WorkflowStage string `json:"workflow_stage"`
ErrorName string `json:"error_name"`
ErrorMessage string `json:"error_message"`
ComponentFingerprint string `json:"component_fingerprint"`
}
type EventSink interface {
AppendClientError(Event) error
}
type Handler struct {
Sink EventSink
}
func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodPost {
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
if r.Header.Get("Content-Type") != "application/json" {
http.Error(w, "content type must be application/json", http.StatusUnsupportedMediaType)
return
}
reader := http.MaxBytesReader(w, r.Body, 8<<10)
decoder := json.NewDecoder(reader)
decoder.DisallowUnknownFields()
var event Event
if err := decoder.Decode(&event); err != nil {
http.Error(w, "invalid event", http.StatusBadRequest)
return
}
if err := requireEOF(decoder); err != nil {
http.Error(w, "invalid event", http.StatusBadRequest)
return
}
if !valid(event) {
http.Error(w, "invalid event", http.StatusUnprocessableEntity)
return
}
if err := h.Sink.AppendClientError(event); err != nil {
http.Error(w, "intake unavailable", http.StatusServiceUnavailable)
return
}
w.WriteHeader(http.StatusAccepted)
}
func requireEOF(decoder *json.Decoder) error {
var extra any
if err := decoder.Decode(&extra); !errors.Is(err, io.EOF) {
return errors.New("request must contain one JSON object")
}
return nil
}
func valid(event Event) bool {
return event.SchemaVersion == 1 &&
event.EventID != "" &&
!event.OccurredAt.IsZero() &&
strings.HasPrefix(event.Route, "/checkout/") &&
event.WorkflowStage == "payment_review" &&
len(event.Release) <= 80 &&
len(event.ErrorName) <= 80 &&
len(event.ErrorMessage) <= 240 &&
len(event.ComponentFingerprint) <= 128
}
In a real deployment, the origin and session checks sit before this handler, deduplication belongs in the sink, and the public response stays uninformative. Rate-limit by a privacy-preserving session or attempt key as well as network address; a public browser endpoint is untrusted input. Never let user-supplied route, release, or error text become an unescaped metric label, because unconstrained label values create cardinality and cost problems. Keep the raw event in an appropriately controlled stream and derive bounded dimensions for metrics.
Rollback safety comes from versioning both sides independently. The current receiver accepts schema version 1 while a new frontend is deployed. A future schema version should be additive or should travel through a distinct compatibility period; the old frontend remains valid during rollback. The release field must identify the actual browser bundle, not merely the backend deployment, because a cached client may continue reporting after the server has moved on. Run contract fixtures from the current build and the previous rollback candidate against the intake handler before deployment.
The receiver itself should emit one structured line for each accepted event and one bounded counter for each rejection reason. A custom appender is an option when a Java service needs to direct an event into its logging pipeline; the Logback manual documents the appender extension point. Keep that integration behind EventSink. Checkout code should know the event contract, not the storage destination.
Compare mechanisms by the page they can justify
The choice is not really “SDK or no SDK.” It is which evidence path can justify waking someone and which failure modes the team is willing to own.
| Mechanism | What it gives the responder | Rollback and operating trade-off |
|---|---|---|
| Boundary plus a small backend intake | An application-defined checkout stage, release, and fingerprint | Small dependency surface, but the team owns validation, grouping, retention, source-map policy, and abuse controls |
| A dedicated browser error SDK | Usually broader capture and an established processing pipeline | More client code and vendor-specific behavior must be tested during releases and rollback |
| Server logs only | Authoritative server actions and an existing operational path | Cannot directly observe a render failure that prevents the next request |
| Browser console collection during support | Rich local detail for a reproducible case | Reactive, manual, and unsuitable as a paging signal |
The custom intake is appropriate when the required event is deliberately narrow, the team already operates an event stream, and rollback independence matters more than automatic enrichment. The catch is that it is not suitable when the team expects session replay, automatic source-map processing, broad framework instrumentation, or a ready-made issue workflow but does not want to build and operate those capabilities. In that case, evaluate a dedicated tool under the same data-minimization and rollback tests. Stick with server-side workflow events when the backend is the authority and the client report would only duplicate them.
No dashboard settles this decision.
Ask what page would fire at 03:00. “JavaScript errors increased” is not actionable; “the new browser release is producing one fingerprint on payment_review, and checkout completion fell outside its normal band” points to a release, a workflow, and a rollback. Your mileage may vary on the exact correlation window, because traffic volume and release cadence determine how quickly a rate becomes meaningful. Test it with replayed, labeled fixtures rather than choosing a threshold from intuition.
Test the failure path before trusting the alert
Start with a synthetic component that throws during render only when a test flag is present. Assert that the fallback remains usable, exactly one schema-valid event reaches a fake EventSink, duplicate event IDs do not create duplicate records, and the buyer path does not wait for the intake response. Then reject an oversized payload, an unknown field, the wrong workflow stage, and a stale schema version. These tests are more valuable than a screenshot of a rising error chart because they exercise the contract a responder depends on.
Deployment testing needs two directions. First, deploy the receiver before the producer and prove the old frontend still works. Second, deploy the producer, then roll it back while the receiver remains current. Keep the prior browser fixture available until caches can no longer serve that bundle. If the alert depends on checkout-completion correlation, inject the synthetic exception only into a non-buyer test path and verify that the rule produces a test notification with the release and fingerprint, not a production page.
Review privacy and cost at the contract, not after ingestion.
Allowlists beat redaction.
Redaction has to anticipate every secret shape. Sampling may be acceptable for a high-volume, repeated fingerprint, but preserve the first event for a new release and track sampled counts separately so a responder does not mistake storage volume for impact. Retention should follow the shortest period needed for incident response and release comparison. None of this requires the checkout bundle to know where records are stored.
Finally, write the runbook around decisions: confirm the affected workflow and release; compare the fingerprint against the previous release; check the independent completion signal; stop or roll back the release when the evidence agrees; and only then inspect detailed events. If the page cannot identify those fields, it is unfinished operational work, even if the chart looks impressive.
Top comments (0)