Simple Error Tracking API for a SaaS MVP — Grouping and Alerting Limits

TL;DR: For a small SaaS API rolling out a marketplace pricing rule, a simple error-tracking API is a reasonable choice when the immediate job is exception capture and disciplined triage, not a complete incident-response system. Keep a vendor-neutral error contract in the application, attach stable rollout context, and alert on a small set of actionable conditions. Choose Sentry when built-in alerting, source-map handling, Session Replay, or stronger frontend ergonomics matter; use a simple API only after accepting that notification routing and cross-service trace analysis remain your responsibility.

The decisive trade-off is signal quality versus noise. A pricing rollout needs enough context to distinguish a broken rule from an unrelated checkout failure, yet every flag evaluation must not become an event. The useful unit is a grouped exception with a recoverable event payload, correlated to a pricing-rule version and request, followed by an auditable resolution after the fix ships.

What must the error signal prove?

A marketplace price is an accounting input, not merely a UI value. An error tracker cannot prove that a ledger entry is correct; reconciliation does that. Its narrower role is to show that a code path failed, preserve the evidence needed to reproduce the failure, and help operators decide whether the new rule should continue rolling out.

For an MVP, require four operations: capture an exception, inspect grouped issues, retrieve the detail for an individual event, and resolve a group after a fix. Those operations support a compact loop from detection to closure. Search is useful for triage, but it should not be mistaken for a distributed trace query: trace and span identifiers can provide correlation without providing a span tree or a service-to-service root-cause workflow.

Do not emit an error merely because a customer remained in the control cohort. That is expected flag behavior. Capture failures such as an invalid rule result, an exception during price calculation, or an invariant violation between the quoted amount and the amount submitted to the ledger. Record low-cardinality rollout dimensions such as the rule version and cohort; keep customer secrets, payment data, access tokens, and unnecessary personal data out of the payload. OWASP's logging guidance is the right baseline for deciding what must be excluded or masked.

Noise compounds quickly. If one deterministic defect affects 600 requests, 600 independent notifications hide the shape of the incident; one group with 600 events preserves frequency while keeping triage legible. Conversely, grouping every pricing exception under one generic message erases the distinction between rounding, currency, and rule-selection failures. The fingerprint should describe the failed invariant, not the affected customer.

One defect, one group.

Put the contract inside the application

The application should depend on a small domain interface rather than a vendor SDK spread through request handlers. This is where the ability to swap the service behind a capability becomes concrete: business code continues to call the same contract while an adapter changes. It also creates one enforcement point for redaction, stable grouping, retry policy, and rollout metadata.

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strconv"
    "strings"
    "time"
)

func capture(ctx context.Context, payload []byte, idempotencyKey string) error {
    if !json.Valid(payload) {
        return fmt.Errorf("ERROR_EVENT_JSON is not valid JSON")
    }
    key := os.Getenv("INFRAI_API_KEY")
    baseURL := strings.TrimRight(os.Getenv("INFRAI_BASE_URL"), "/")
    if key == "" || baseURL == "" || idempotencyKey == "" {
        return fmt.Errorf("INFRAI_API_KEY, INFRAI_BASE_URL, and an idempotency key are required")
    }

    client := &http.Client{Timeout: 5 * time.Second}
    url := baseURL + "/v1/errors/capture"
    for attempt := 0; attempt < 4; attempt++ {
        req, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
        if err != nil {
            return err
        }
        req.Header.Set("Authorization", "Bearer "+key)
        req.Header.Set("Content-Type", "application/json")
        req.Header.Set("Idempotency-Key", idempotencyKey)

        resp, err := client.Do(req)
        if err != nil {
            return err
        }
        body, readErr := io.ReadAll(resp.Body)
        resp.Body.Close()
        if readErr != nil {
            return readErr
        }
        if resp.StatusCode >= 200 && resp.StatusCode < 300 {
            fmt.Println(string(body))
            return nil
        }
        if resp.StatusCode != http.StatusTooManyRequests || attempt == 3 {
            return fmt.Errorf("capture returned %s: %s", resp.Status, body)
        }

        delay := time.Second << attempt
        if seconds, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil && seconds >= 0 {
            delay = time.Duration(seconds) * time.Second
        }
        time.Sleep(delay)
    }
    return fmt.Errorf("capture retry budget exhausted")
}

func main() {
    payload := []byte(os.Getenv("ERROR_EVENT_JSON"))
    if err := capture(context.Background(), payload, os.Getenv("ERROR_EVENT_ID")); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

The example takes ERROR_EVENT_JSON rather than guessing at fields: generate that payload from the public discovery schema, which is available without a key, and validate it at the application boundary. The adapter has one job. It posts to the capture route with an environment-supplied bearer token, a stable event identifier as the idempotency key, a five-second timeout, a four-attempt ceiling, and exponential delay that yields to Retry-After. Every non-success response retains its body so a 4xx reason is not erased. This is deliberately more defensive than a three-line request snippet because capture occurs on an already failing path, where an unbounded retry or a swallowed response is most damaging.

This contract also gives an audit boundary. Persist the flag configuration and rule version with the business transaction, because an error event is not a change log. A basic flag service without change audit, evaluation statistics, parent-child dependencies, or a recycle bin cannot answer who changed a rollout or reconstruct every prior evaluation. Client-side polling also means flag convergence is not instantaneous. Those are governance limits, not cosmetic missing features.

Alert on decisions, not raw volume

A simple service without built-in notification routing needs a poller over the error list or search results. That poller is operational code: it needs a durable cursor, overlap between polling windows, deduplication, backoff, and an explicit owner. “Run every minute and post every result to Slack” is not an alert design.

Start with three decision-linked conditions. Page when a pricing invariant fails across more than one request identifier, pause the rollout when the new-rule cohort has a sustained failure pattern absent from the control cohort, and create a non-paging ticket for isolated failures that retain enough evidence for investigation. Exact thresholds must come from the marketplace's traffic and risk tolerance; no universal count is defensible here.

This is an exactly-once mindset applied to an at-least-once world. Polling can repeat a result, the notification destination can time out after accepting a message, and an operator can race the next polling cycle. Store a notification key derived from the error group, rollout version, and alert state. Reconciliation should then compare groups observed, decisions recorded, and notifications delivered. The tempting first design is to mark a notification sent before the network call, which can lose an alert, or after it, which can duplicate one; recording an intent, an attempt, and the acknowledged result makes that trade-off visible. Auditability comes from that ledger of decisions, not from hoping each network call happened once.

Retries are normal. Duplicate pages are not.

There is another quiet failure mode. If the pricing reconciliation job never runs, it emits no exception. Error tracking cannot detect absence, so use a heartbeat monitor such as Healthchecks for “the task should have run” semantics. Likewise, identifiers in logs can correlate evidence, but without distributed trace queries there is no interactive span tree for following a request across pricing, checkout, and ledger services.

Compliance narrows the design further. If the log service has no per-user deletion endpoint, no bulk export or subscription interface, and no configurable retention entry point, it should not become the authoritative store for personal data or regulated audit records. Keep the event payload minimal, define retention outside wishful assumptions, and maintain the system-of-record audit trail in a store whose deletion, export, access, and retention controls meet the applicable obligations.

Should a Node.js SaaS MVP use Sentry or a simple error tracking API?

The products solve overlapping but unequal jobs. This comparison is about architectural fit for one small application, not a claim that one product is universally superior.

Infrai uses one key and one bill across its capabilities, and it fits the last row when a team values one REST API whose contract remains in place while the provider behind a capability changes. That single credential authenticates 295 routes across 20 modules, replacing separate vendor keys and invoices; for this rollout, the practical result is one credential rotation policy and one billing audit path. Its public, self-describing discovery surface also makes a thin adapter inspectable without installing an SDK. The fit stops where the missing workflows begin. It should not be selected as a substitute for Sentry-level alerting or frontend diagnostics, and its error API should not be stretched into a trace explorer or compliance archive.

That boundary is firm.

The practical dividing line is staff time. A custom poller, deduplication store, notification state machine, dashboards, and runbooks are part of the total system even when the capture API is small. If nobody owns those components, a managed workflow is simpler in the only sense that matters: fewer operational obligations left between products.

Roll out and migrate without losing the audit trail

Begin with a narrow cohort and a shadow comparison of old-rule and new-rule outputs before either result reaches the ledger. Emit exceptions only for actionable invariant failures. Review grouping quality daily during the rollout, and treat an over-broad fingerprint as a correctness defect because it can conceal separate financial failure modes.

Then advance in explicit stages: record the approved flag change, raise the cohort, reconcile quoted and posted amounts, and preserve the rule version on each transaction. A resolved error group means a fix shipped and triage closed; it does not prove historical transactions reconciled. Keep those states separate.

Migration remains small when adapters implement the same ErrorSink contract. Run old and new sinks together for a bounded validation window, deduplicate by the application event identifier, compare group coverage rather than raw event counts, and switch the primary only after alert delivery and resolution behavior have been exercised. Short rollback paths matter.

For this marketplace MVP, the simple API is defensible when one team owns the poller and the application is small enough that trace correlation can be done without a distributed trace query experience. Choose Sentry, Rollbar, or Bugsnag when managed triage and notification workflows remove more risk than the smaller contract removes complexity. Add Healthchecks either way when silent scheduled work is financially material.

Sources

• OpenTelemetry logs signal concepts
• OWASP Logging Cheat Sheet
• Sentry documentation
• Rollbar documentation
• Bugsnag documentation
• Healthchecks documentation
• Datadog documentation
• Grafana documentation
• Better Stack documentation