error-handling

name	error-handling
description	Standardize application error handling—taxonomy, propagation, response shapes, logging, and correlation IDs—when the task is to improve consistency of existing error behavior across a codebase.

Error Handling

Overview

Standardize error handling across a codebase by implementing a unified error taxonomy, stable error codes, proper propagation chains, and structured logging. The core principle: every error must be categorized, coded, wrapped with context, and split into a safe user-facing message and a detailed internal log entry.

When to use

• The task is to standardize how an existing codebase models, propagates, logs, and returns errors.
• The user needs an error taxonomy, error classes, response envelopes, or correlation-aware logging patterns.
• The problem is inconsistency across layers, services, or endpoints rather than a single failing bug.
• The deliverable is an error-handling framework or pattern, not one-off troubleshooting.

Do NOT use when:

• The task is debugging a specific runtime failure.
• The request is about monitoring, alert routing, or dashboards rather than application error design.
• The work is only input validation or business rules with no broader error-model concern.

Response format

Always structure the final response with these top-level sections, in this order:

1. Summary — state the task, scope, and main conclusion in 1-3 sentences.
2. Decision / Approach — state the key classification, assumptions, or chosen path.
3. Artifacts — provide the primary deliverable(s) for this skill. Use clear subheadings for multiple files, commands, JSON payloads, queries, or documents.
4. Validation — state checks performed, important risks, caveats, or unresolved questions.
5. Next steps — list concrete follow-up actions, or write None if nothing remains.

Rules:

• Do not omit a section; write None when a section does not apply.
• If files are produced, list each file path under Artifacts before its contents.
• If commands, JSON, SQL, YAML, or code are produced, put each artifact in fenced code blocks with the correct language tag when possible.
• Keep section names exactly as written above so output stays predictable across skills.

Workflow

1. Audit existing error handling

Scan the codebase for current error patterns:

• Search for try/catch, try/except, .catch(), rescue, error middleware
• Identify swallowed exceptions (empty catch blocks, catch-and-ignore)
• Find bare throws/raises without context wrapping
• Note inconsistent error response formats across endpoints
• Check for leaked internal details in user-facing responses

Output: A list of error handling gaps and inconsistencies.

2. Define the error taxonomy

Create error categories that map to HTTP status codes (for APIs) or exit conditions (for services). Every error in the system must belong to exactly one category.

Category	HTTP Status	Error Code Prefix	Description
validation	400	ERR_VALIDATION_	Invalid input, malformed request
authentication	401	ERR_AUTH_	Missing or invalid credentials
authorization	403	ERR_FORBIDDEN_	Valid credentials but insufficient access
not_found	404	ERR_NOT_FOUND_	Requested resource does not exist
conflict	409	ERR_CONFLICT_	State conflict (duplicate, version mismatch)
rate_limit	429	ERR_RATE_LIMIT_	Too many requests
internal	500	ERR_INTERNAL_	Unexpected server error
service_unavailable	503	ERR_UPSTREAM_	Dependency failure (DB, external API)

3. Implement error class hierarchy

Create a base error class and category-specific subclasses. Every error class must carry:

• code — Stable string code clients can match on (e.g., ERR_USER_NOT_FOUND)
• message — Safe, user-facing message (no stack traces, no internal paths)
• statusCode — HTTP status code for API responses
• category — Error taxonomy category
• details — Optional structured data (field validation errors, constraints)
• cause — Original error for propagation chain (preserves stack trace)

TypeScript example:

export class AppError extends Error {
  public readonly code: string;
  public readonly statusCode: number;
  public readonly category: string;
  public readonly details?: Record<string, unknown>;
  public readonly isOperational: boolean;

  constructor(params: {
    code: string;
    message: string;
    statusCode: number;
    category: string;
    details?: Record<string, unknown>;
    cause?: Error;
    isOperational?: boolean;
  }) {
    super(params.message, { cause: params.cause });
    this.code = params.code;
    this.statusCode = params.statusCode;
    this.category = params.category;
    this.details = params.details;
    this.isOperational = params.cause !== undefined
      ? true
      : (params.isOperational ?? true);
    this.name = this.constructor.name;
    Error.captureStackTrace(this, this.constructor);
  }
}

export class ValidationError extends AppError {
  constructor(
    message: string,
    details?: Record<string, unknown>,
    cause?: Error,
  ) {
    super({
      code: "ERR_VALIDATION",
      message,
      statusCode: 400,
      category: "validation",
      details,
      cause,
    });
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string, identifier: string, cause?: Error) {
    super({
      code: `ERR_NOT_FOUND_${resource.toUpperCase()}`,
      message: `${resource} not found`,
      statusCode: 404,
      category: "not_found",
      details: { resource, identifier },
      cause,
    });
  }
}

export class ConflictError extends AppError {
  constructor(
    message: string,
    details?: Record<string, unknown>,
    cause?: Error,
  ) {
    super({
      code: "ERR_CONFLICT",
      message,
      statusCode: 409,
      category: "conflict",
      details,
      cause,
    });
  }
}

export class AuthenticationError extends AppError {
  constructor(message = "Authentication required", cause?: Error) {
    super({
      code: "ERR_AUTH_INVALID",
      message,
      statusCode: 401,
      category: "authentication",
      cause,
    });
  }
}

export class AuthorizationError extends AppError {
  constructor(message = "Insufficient permissions", cause?: Error) {
    super({
      code: "ERR_FORBIDDEN",
      message,
      statusCode: 403,
      category: "authorization",
      cause,
    });
  }
}

export class RateLimitError extends AppError {
  constructor(retryAfterSeconds?: number, cause?: Error) {
    super({
      code: "ERR_RATE_LIMIT",
      message: "Too many requests",
      statusCode: 429,
      category: "rate_limit",
      details: retryAfterSeconds
        ? { retryAfter: retryAfterSeconds }
        : undefined,
      cause,
    });
  }
}

export class InternalError extends AppError {
  constructor(message: string, cause?: Error) {
    super({
      code: "ERR_INTERNAL",
      message: "An unexpected error occurred",
      statusCode: 500,
      category: "internal",
      cause,
      isOperational: false,
    });
  }
}

Python equivalent:

class AppError(Exception):
    def __init__(
        self,
        code: str,
        message: str,
        status_code: int,
        category: str,
        details: dict | None = None,
        cause: Exception | None = None,
        is_operational: bool = True,
    ):
        super().__init__(message)
        self.code = code
        self.message = message
        self.status_code = status_code
        self.category = category
        self.details = details or {}
        self.is_operational = is_operational
        self.__cause__ = cause

class NotFoundError(AppError):
    def __init__(self, resource: str, identifier: str, cause: Exception | None = None):
        super().__init__(
            code=f"ERR_NOT_FOUND_{resource.upper()}",
            message=f"{resource} not found",
            status_code=404,
            category="not_found",
            details={"resource": resource, "identifier": identifier},
            cause=cause,
        )

class ValidationError(AppError):
    def __init__(self, message: str, details: dict | None = None, cause: Exception | None = None):
        super().__init__(
            code="ERR_VALIDATION",
            message=message,
            status_code=400,
            category="validation",
            details=details,
            cause=cause,
        )

4. Implement error propagation rules

Never swallow exceptions. Every catch block must either:

1. Re-raise the error unchanged (if this layer can't add context)
2. Wrap the error in a domain-specific error with the original as cause
3. Handle the error completely (log it, return a response, trigger recovery)

Always preserve the chain. When wrapping, pass the original error as cause so the full stack trace is available in logs:

// WRONG: swallows the original error
try {
  await db.query(sql);
} catch (err) {
  throw new Error("Database query failed"); // original error lost
}

// RIGHT: wraps with context, preserves cause
try {
  await db.query(sql);
} catch (err) {
  throw new InternalError("Database query failed", err as Error);
}

5. Separate user-facing from internal errors

User-facing response — safe, minimal, actionable:

{
  "error": {
    "code": "ERR_NOT_FOUND_USER",
    "message": "User not found",
    "details": {
      "resource": "user",
      "identifier": "usr_abc123"
    }
  },
  "requestId": "req_7f3a2b1c"
}

Internal log entry — full diagnostic context:

{
  "level": "error",
  "code": "ERR_NOT_FOUND_USER",
  "message": "User not found",
  "category": "not_found",
  "correlationId": "req_7f3a2b1c",
  "userId": "usr_abc123",
  "path": "/api/users/usr_abc123",
  "method": "GET",
  "stack": "NotFoundError: User not found\n    at UserService.getById ...",
  "cause": "MongoError: connection refused at 10.0.0.5:27017",
  "timestamp": "2026-03-06T10:15:32.456Z",
  "service": "user-api",
  "environment": "production"
}

Rules:

• Never expose stack traces, file paths, or database errors to users
• Never expose internal service names or infrastructure details
• Always include the error code in both user response and log
• Always include a requestId / correlationId in both
• Log the full causal chain internally; show only the top-level message to users
• For InternalError (500), always use a generic message: "An unexpected error occurred"

6. Implement error response middleware

Centralize error-to-response conversion in middleware (Express) or exception handlers (FastAPI, Django). This is the single place where errors become HTTP responses.

// Express error middleware
function errorHandler(
  err: Error,
  req: Request,
  res: Response,
  next: NextFunction,
) {
  const correlationId = req.headers["x-request-id"] || crypto.randomUUID();

  if (err instanceof AppError) {
    // Operational error — expected, safe to expose
    logger.error({
      code: err.code,
      message: err.message,
      category: err.category,
      correlationId,
      path: req.path,
      method: req.method,
      stack: err.stack,
      cause: err.cause?.message,
    });

    return res.status(err.statusCode).json({
      error: {
        code: err.code,
        message: err.message,
        ...(err.details && { details: err.details }),
      },
      requestId: correlationId,
    });
  }

  // Unexpected error — do NOT expose details
  logger.error({
    code: "ERR_INTERNAL",
    message: err.message,
    category: "internal",
    correlationId,
    path: req.path,
    method: req.method,
    stack: err.stack,
  });

  return res.status(500).json({
    error: {
      code: "ERR_INTERNAL",
      message: "An unexpected error occurred",
    },
    requestId: correlationId,
  });
}

7. Add structured error logging

Every error log entry must include:

Field	Required	Description
level	Yes	error, warn, or fatal
code	Yes	Stable error code (e.g., ERR_NOT_FOUND_USER)
message	Yes	Human-readable description
category	Yes	Error taxonomy category
correlationId	Yes	Request ID for tracing across services
path	Yes	Request path or operation name
method	Yes	HTTP method or operation type
stack	Yes	Full stack trace
cause	No	Original error message if wrapped
timestamp	Yes	ISO 8601 timestamp
service	Yes	Service name for multi-service architectures
userId	No	Authenticated user ID if available
details	No	Structured error details (validation fields)

Checklist

• Error taxonomy defined with categories mapping to HTTP status codes
• Base error class implemented with code, message, statusCode, category, cause
• Category-specific error subclasses created (validation, auth, not-found, etc.)
• Error codes are stable strings clients can match on programmatically
• All catch blocks either re-raise, wrap with context, or fully handle
• No swallowed exceptions (empty catch blocks)
• User-facing responses contain only code, message, and safe details
• Internal logs contain full stack traces, causal chains, and request context
• Correlation ID flows through from request to response to logs
• Centralized error middleware converts errors to consistent HTTP responses
• 500 errors always use generic message, never expose internals

Error Response Schema

All API error responses must follow this schema:

{
  "error": {
    "code": "ERR_VALIDATION",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "constraint": "Must be a valid email address",
      "received": "not-an-email"
    }
  },
  "requestId": "req_7f3a2b1c"
}

Field	Type	Required	Description
error.code	string	Yes	Stable error code for programmatic matching
error.message	string	Yes	Human-readable description, safe for users
error.details	object	No	Structured context (validation fields, etc.)
requestId	string	Yes	Correlation ID for support and debugging

Common mistakes

Mistake	Fix
Swallowing exceptions in empty catch blocks	Every catch must re-raise, wrap, or fully handle. Log at minimum.
Leaking stack traces to API consumers	Error middleware must strip internals. Only expose code + message + safe details.
Using HTTP status codes as error codes	Status codes are transport-level. Use stable string codes (ERR_USER_NOT_FOUND) for programmatic use.
Inconsistent error response format	Centralize in error middleware. Every error response uses the same JSON schema.
Throwing raw strings instead of error objects	Always throw typed error instances with code, category, and cause chain.
Missing correlation IDs	Generate a request ID at the edge (middleware/gateway) and propagate through all layers and logs.
Logging user-facing message only	Internal logs must include stack trace, cause chain, request context, and correlation ID.
Different error formats per endpoint	One error middleware, one response schema. Endpoints throw typed errors; middleware formats responses.
Catching too broadly (catch Exception)	Catch specific error types when possible. Use broad catch only at the top-level error boundary.
Not distinguishing operational vs programmer errors	Operational errors (bad input, not found) are expected. Programmer errors (null deref) need alerts.

Key principles

1. Every error gets a stable code — HTTP status codes change meaning across contexts. String error codes like ERR_USER_NOT_FOUND are stable contracts that clients, monitoring, and documentation can rely on. Never use numeric codes alone.

2. Never swallow, always wrap — Empty catch blocks hide bugs. Every caught error must be re-raised, wrapped with domain context (preserving the original as cause), or fully handled. The causal chain must survive from origin to log.

3. User-facing and internal are separate concerns — Users see a safe message and an error code. Logs see the full stack trace, causal chain, correlation ID, and request context. The error middleware is the boundary between these two worlds.

4. Correlation IDs connect everything — A single request ID generated at the edge must appear in the HTTP response, every log entry, and any downstream service calls. Without this, debugging production errors across services is impossible.

5. Centralize the error boundary — One error middleware, one response schema, one logging format. Individual endpoints throw typed errors; they never format error responses directly. This eliminates inconsistency.

Optimization Notes

• Preserve the user's requested output shape exactly and do not substitute generic advice for concrete artifacts.
• Include exact commands, code structures, protocol fields, tags, parameters, file paths, or deliverable sections when the task asks for them.
• Make safety gates explicit before irreversible, destructive, externally visible, or compliance-sensitive actions.
• For multi-step work, present steps in execution order and include validation or rollback checks where relevant.
• Avoid overfitting to a single eval example: express lessons as reusable rules, not as task-specific answers.