atelier/examples/good/error-handler.md

Good Example: Error Handler

An error handler that follows Atelier's Errors principles. Each aspect cites the principle it satisfies.

The Handler

// Centralized error middleware
import { v4 as uuidv4 } from 'uuid';

type AppError = {
  code: string;
  message: string;
  statusCode: number;
  details?: Record<string, unknown>;
  cause?: unknown;
};

function errorHandler(err: unknown, req: Request, res: Response, next: NextFunction) {
  const requestId = req.headers['x-request-id'] as string || uuidv4();

  const appError = normalizeError(err, requestId);

  // Log with full context (server-side only)
  logger.error({
    request_id: requestId,
    code: appError.code,
    message: appError.message,
    details: appError.details,
    path: req.path,
    method: req.method,
    user_id: req.user?.id,
    stack: err instanceof Error ? err.stack : undefined,
  });

  // Respond with safe, structured error
  res.status(appError.statusCode).json({
    error: {
      code: appError.code,
      message: appError.message,
      request_id: requestId,
      ...(appError.details ? { details: appError.details } : {}),
    },
  });
}

function normalizeError(err: unknown, requestId: string): AppError {
  // Known error types — preserve their code and status
  if (err instanceof ValidationError) {
    return {
      code: err.code,
      message: err.message,
      statusCode: 422,
      details: err.details,
    };
  }
  if (err instanceof NotFoundError) {
    return { code: err.code, message: err.message, statusCode: 404 };
  }
  if (err instanceof AuthError) {
    return { code: 'AUTH_REQUIRED', message: 'Authentication required', statusCode: 401 };
  }

  // Unknown error — fail securely, do not leak internals
  return {
    code: 'INTERNAL_ERROR',
    message: 'An internal error occurred',
    statusCode: 500,
    cause: err,
  };
}

What Makes It Good

Errors are Data (Errors P1)

• Errors are normalized into a structured AppError type. They are values, not raw exceptions.
• The code is a stable, machine-consumable string (VALIDATION_FAILED, not a free message).
• The handler treats every error as data to be transformed, not a flow to be caught.

Fail Loudly (Errors P2)

• No catch (e) {}. Every error reaches the handler.
• No silent swallowing. The error is logged and responded to.
• The middleware is centralized — every route uses it. No route can "forget" to handle errors.

Fail Specifically (Errors P3)

• ValidationError → 422 with code: err.code (specific, e.g., INVALID_EMAIL).
• NotFoundError → 404 with code: err.code (e.g., USER_NOT_FOUND).
• Unknown → 500 with INTERNAL_ERROR (generic only when truly unknown).
• Never "Something went wrong" — always a specific code.

Preserve Context (Errors P4)

• Server-side log includes: request_id, code, message, details, path, method, user_id, stack.
• Client-side response includes: code, message, request_id, details.
• The request_id ties the client response to the server log. Debuggable.

Recoverable When Possible (Errors P5)

• 422 (validation) — the client can fix and retry.
• 401 (auth) — the client can re-auth and retry.
• 404 (not found) — the client can correct the ID.
• Only 500 is "the server has a bug" — not recoverable by the client.

Unrecoverable Means Stop (Errors P6)

• A 500 does not limp on. It logs and returns.
• The server does not try to "recover" from an unknown error by guessing. It fails fast.

Errors are Boundaries (Errors P7)

• The middleware is the boundary. Internal error types (ValidationError, NotFoundError) are translated to HTTP responses here.
• Internal code throws domain errors; the boundary translates to HTTP. No internal error type leaks to the client.

User-Facing Errors are UX (Errors P8)

• message is for the developer (log + response). The client UI renders a user-facing message based on code.
• INTERNAL_ERROR → "Something went wrong. We're on it." (user-facing), not the stack.

Errors are Logged (Errors P9)

• Every error is logged at ERROR level with full context.
• The handling is the recovery (return a response); the log is the memory (investigate later).

Errors Don't Lie (Errors P10)

• The status code matches the error type. 422 for validation, not 200.
• INTERNAL_ERROR is returned only for unknown errors. Known errors get their specific code.
• Never claim success on failure. Never claim failure on success.

Security (Security P5 Output Safety, P9 Secret Hygiene)

• Unknown errors return INTERNAL_ERROR with no internal details. No stack trace to the client.
• The stack is logged server-side, never sent to the client.
• The error message does not echo the input (which may contain a token).

Observability (Observability P2 Correlation, P3 Context)

• request_id on every error. Correlatable across services.
• Sufficient context in the log: path, method, user_id. "What was the user doing?" is answerable.

What This Example Does NOT Do (And Why That's Good)

• Does not catch (e) { return null } — silent failure (P2).
• Does not return 200 with { error: ... } — the status code lies (API P9).
• Does not send the stack trace to the client — information leak (Security P5).
• Does not log the request body — may contain secrets (Security P9, Observability P6).
• Does not use a generic Error("error") — not specific (P3).