Error handling in Node.js that makes production debuggable

What is the difference between operational and programmer errors?

Trying to recover from a programmer error means continuing with a process whose state you no longer understand. Restarting is not a failure of engineering; it is the only honest response to unknown state.

How should errors carry context?

class AppError extends Error {
  constructor(
    message: string,
    readonly code: string,
    readonly status: number,
    readonly context: Record<string, unknown> = {},
    options?: { cause?: unknown }
  ) {
    super(message, options);
    this.name = new.target.name;
  }
}

throw new AppError("Payment provider timed out", "payment_timeout", 502,
  { orderId, provider: "stripe", attempt: 2 }, { cause: err });

A stack trace tells you where. Context tells you which order, which customer, which attempt — the difference between a five-minute fix and an afternoon of guessing.

How do you handle async errors correctly?

1. 1Always await or return a promise. A floating promise's rejection becomes an unhandled rejection with no context.
2. 2Register process handlers for unhandledRejection and uncaughtException — log, flush, then exit rather than continuing.
3. 3In Express-style frameworks, wrap async handlers so rejections reach the error middleware.
4. 4Use Promise.allSettled when partial failure is acceptable, and inspect every result.
5. 5Set explicit timeouts on all outbound calls; a hung request produces no error at all.

What should logs look like?

logger.error({
  err,                       // serialised with stack and cause
  requestId: ctx.requestId,
  userId: ctx.userId,
  route: "POST /orders",
  durationMs: 1832,
}, "order creation failed");

• One JSON object per line so log platforms can index fields.
• A request id generated at the edge and propagated through every layer, including background jobs.
• Levels used consistently: error means a human should look, warn means it is degraded, info is the audit trail.
• Never log secrets, tokens, full card numbers or personal data you would not want in a support ticket.
• Sample high-volume info logs; keep 100% of errors.

What should the client receive?

A stable machine-readable code, a human-readable message that is safe to display, and the request id. Never a stack trace — it leaks file paths, dependency versions and sometimes queries.

{
  "error": {
    "code": "payment_timeout",
    "message": "We could not reach the payment provider. No charge was made.",
    "requestId": "req_01HQ8Z3F2K"
  }
}