Error Handling Platform Skill

A Claude Code skill for implementing robust error handling across your application — covering error classification, structured logging, error boundaries, retry strategies, and user-facing error messages.

When to Use This Skill

Choose this skill when:

• Designing error handling architecture for a new application
• Implementing structured error classes with error codes
• Setting up error logging, monitoring, and alerting
• Creating user-friendly error messages from technical errors
• Building retry logic for transient failures (network, database)
• Adding error boundaries to React applications

Consider alternatives when:

• You need monitoring/alerting infrastructure (use Datadog, Sentry)
• You need log aggregation at scale (use an ELK/Loki skill)
• You need to debug a specific error (just debug it directly)

Quick Start

Copy
# Add to your Claude Code project
claude mcp add error-platform

# Design error handling for your app
claude "set up error handling architecture for our Express API"

Copy
// src/errors/AppError.ts - Base error class
export class AppError extends Error {
  readonly statusCode: number;
  readonly code: string;
  readonly isOperational: boolean;

  constructor(message: string, statusCode: number, code: string) {
    super(message);
    this.statusCode = statusCode;
    this.code = code;
    this.isOperational = true;
    Error.captureStackTrace(this, this.constructor);
  }
}

export class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} with id '${id}' not found`, 404, 'NOT_FOUND');
  }
}

export class ValidationError extends AppError {
  constructor(message: string) {
    super(message, 400, 'VALIDATION_ERROR');
  }
}

export class UnauthorizedError extends AppError {
  constructor(message = 'Authentication required') {
    super(message, 401, 'UNAUTHORIZED');
  }
}

Core Concepts

Error Classification

Category	Status Code	Retry	Log Level	Example
Validation	400	No	warn	Invalid email format
Authentication	401	No	warn	Expired JWT token
Authorization	403	No	warn	Insufficient permissions
Not Found	404	No	info	Resource doesn't exist
Conflict	409	No	warn	Duplicate email registration
Rate Limited	429	Yes (backoff)	warn	Too many requests
Server Error	500	Yes (limited)	error	Unhandled exception
Service Unavailable	503	Yes (backoff)	error	Database connection lost

Global Error Handler

Copy
// src/middleware/errorHandler.ts
export function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
  if (err instanceof AppError) {
    // Operational error: expected, safe to send to client
    logger.warn({ code: err.code, message: err.message, path: req.path });
    return res.status(err.statusCode).json({
      error: { code: err.code, message: err.message }
    });
  }

  // Programming error: unexpected, don't leak details
  logger.error({ err, path: req.path, method: req.method });
  return res.status(500).json({
    error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' }
  });
}

Retry Strategy

Copy
async function withRetry<T>(
  fn: () => Promise<T>,
  options: { maxRetries: number; baseDelay: number; maxDelay: number }
): Promise<T> {
  let lastError: Error;
  for (let attempt = 0; attempt <= options.maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;
      if (attempt === options.maxRetries) break;
      const delay = Math.min(
        options.baseDelay * Math.pow(2, attempt) + Math.random() * 1000,
        options.maxDelay
      );
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
  throw lastError!;
}

Configuration

Parameter	Type	Default	Description
log_level	string	"error"	Minimum log level: debug, info, warn, error
include_stack_trace	boolean	false	Include stack traces in API responses (dev only)
max_retries	number	3	Default retry count for transient errors
base_retry_delay	number	1000	Base delay in ms for exponential backoff
error_reporting	string	"sentry"	Error reporting service: sentry, datadog, none
sanitize_errors	boolean	true	Remove sensitive data from error responses
error_code_prefix	string	""	Prefix for error codes (e.g., "APP_")

Best Practices

1. Distinguish operational errors from programming errors — operational errors (invalid input, timeout) are expected and should be handled gracefully; programming errors (null reference, type error) indicate bugs and should be logged and investigated.

2. Never expose internal error details to API consumers — send structured error codes and human-readable messages to clients; log the full stack trace and context server-side for debugging.

3. Use exponential backoff with jitter for retries — linear or constant-interval retries can overwhelm a recovering service; exponential backoff with random jitter spreads retry load over time.

4. Implement error boundaries at every layer — API routes need try-catch, React components need ErrorBoundary, database operations need transaction rollback; each layer should handle errors appropriate to its level.

5. Assign unique error codes, not just HTTP status codes — AUTH_TOKEN_EXPIRED is more actionable than 401 Unauthorized; error codes help both developers and users identify specific problems.

Common Issues

Errors are swallowed silently — Empty catch blocks (catch {}) hide errors. Always log caught errors at minimum; if you intentionally ignore an error, add a comment explaining why.

Retry logic retries non-retryable errors — Retrying a 400 validation error wastes resources and will always fail. Only retry transient errors (5xx, timeouts, network failures) and maintain a list of non-retryable error codes.

Error messages leak sensitive data — Stack traces, database queries, and file paths in error responses give attackers information. Use sanitize_errors: true and review error responses in staging before production.