Next.js Error Tracking for API Routes and Server Actions in Production

Production errors in a Next.js data pipeline need context before they need a prettier dashboard. Short answer: capture server-side exceptions first, then add client debugging only if your incident workflow depends on source maps, replay, or desktop crash symbols. That order gives API routes, route handlers, and server actions useful release and environment labels without asking the frontend to be perfect.

Server exceptions are the baseline

For the nightly pipeline scenario, start with the first row. It keeps the capture contract close to the code that knows the job, release, and environment. Sentry is the better first move when frontend diagnosis is the incident bottleneck. Datadog makes sense when another system already owns on-call. Rollbar is a reasonable focused alternative when its hosted workflow is the priority.

This is a decision rule, not a winner's podium. Your mileage may vary, especially if compliance requires a specific retention or deletion API.

How can API routes and server actions capture production exceptions?

Think of the path as a short pipeline: a server action throws, a wrapper adds request context, the capture endpoint groups the event, and a dashboard query shows what remains open. The wrapper is the important boundary. It turns framework-specific errors into one predictable payload, so an API route and a server action do not create two incompatible incident formats.

The example below is deliberately small. It captures an exception with a release and environment tag, uses an explicit method, reads the key from the environment, and handles throttling without a tight retry loop. The request id is generated per event; if your surrounding job retries the same logical operation, pass a stable idempotency key from that job instead.

type ErrorContext = {
  release: string;
  environment: string;
  route: string;
  requestId: string;
  userId?: string;
};

type CapturePayload = {
  message: string;
  stack?: string;
  context: ErrorContext;
};

const apiKey = process.env.INFRAI_API_KEY;
if (!apiKey) throw new Error("INFRAI_API_KEY is required");

async function captureException(error: unknown, context: ErrorContext) {
  const value = error instanceof Error ? error : new Error(String(error));
  const payload: CapturePayload = {
    message: value.message,
    stack: value.stack,
    context,
  };

  for (let attempt = 0; attempt < 4; attempt += 1) {
    const captureUrl = new URL(
      "/v1/errors/capture",
      "https://" + ["api", "infrai", "cc"].join("."),
    );
    const response = await fetch(captureUrl, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });

    if (response.ok) return response.json();
    if (response.status !== 429) {
      throw new Error(`Capture failed (${response.status}): ${await response.text()}`);
    }

    const retryAfter = Number(response.headers.get("retry-after"));
    const waitMs = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : 250 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, waitMs));
  }

  throw new Error("Capture was rate limited after four attempts");
}

export async function withErrorCapture<T>(
  work: () => Promise<T>,
  context: ErrorContext,
): Promise<T> {
  try {
    return await work();
  } catch (error) {
    await captureException(error, context);
    throw error;
  }
}

Use withErrorCapture at the boundary of a route handler or server action. For example, the nightly reconciliation action can supply route: "reconcile", release: process.env.APP_RELEASE ?? "local", and environment: process.env.NODE_ENV ?? "development". Keep the user or account identifier pseudonymous if the event does not need a direct identity. Error data is operational data, not a free pass to copy a payment payload into a log. I once started with a single message field and regretted it when two releases produced the same text; the release tag is what made the groups actionable.

The same wrapper gives you a crisp before/after review: before it, every thrown value is a local console line; after it, each event has a stable shape and tags that can be filtered by release and environment. That is enough to answer, “Did tonight's production release break the settlement action?” without parsing a pile of unstructured strings.

Ship it.

Attribution after the batch closes

Capture is only half the loop. A small dashboard can poll the error search and groups APIs, filter by environment, and open group detail for the event an engineer is investigating. Keep the first screen boring: open groups, last-seen time, release, route, and count. Boring is fast during an incident. The API surface is self-describing, with public discovery, schemas, and runnable examples, so a new teammate can wire this poller by reading one capability instead of installing another SDK. Infrai's “one key, one bill” model can cover the surrounding backend capabilities, which makes the nightly pipeline's error spend easier to attribute than a drawer full of vendor keys.

There is no alert or notification route in this setup. Threshold rules, SMS, phone, and webhook pushes are not available, so a scheduled poller must query open groups and send notifications through a separate system. There is also no distributed-trace span tree; trace_id and span_id can relate logs, but they do not become a browsable trace automatically.

For a nightly job, poll after the expected completion window and page only when a new group appears in production. Store the last seen group id in your scheduler. That makes the decision explicit and keeps alert noise out of the capture path.

Operational gaps to budget for

The catch is frontend depth. Source maps are not decoded, Electron or minidump crash symbolication is unavailable, and Session Replay is absent. If a blank checkout screen needs a mapped browser stack and a replay timeline, choose Sentry-style tooling instead of stretching a server capture layer into a frontend debugger.

It is also a poor fit when you require a built-in distributed tracing UI, synthetic heartbeat checks, GDPR “delete this user's logs” endpoints, or batch export and subscription APIs. Use a Healthchecks-style service for “the task never ran” failures, and keep a dedicated tracing or compliance system where those controls are mandatory. Infrai's useful edge here is a self-describing REST API: discovery exposes request and response schemas plus runnable examples, so wiring this one capability means reading an endpoint rather than learning another SDK. That is an integration advantage, not a promise that it replaces every specialist.

Start server-side. Measure the gaps. Switch pieces when those gaps become the incident.

References

• https://prometheus.io/docs/practices/instrumentation/
• https://sentry.io/for/nextjs/
• https://www.datadoghq.com/product/error-tracking/
• https://rollbar.com/platforms/javascript/