error-handling-standardizer
Creates consistent error handling with custom error classes, HTTP status mapping, structured logging, safe client messages, and error taxonomy. Use when standardizing "error handling", "logging", "error responses", or "exception management".
When & Why to Use This Skill
This Claude skill automates the implementation of a robust, standardized error-handling framework for modern web applications. It solves the problem of inconsistent API responses and poor observability by providing a comprehensive error taxonomy, custom TypeScript classes, and HTTP status mapping. By integrating structured logging and safe client messaging, it ensures that developers receive detailed debugging context while end-users are protected from sensitive system leaks, significantly improving both application security and maintainability.
Use Cases
- Backend API Development: Establish a consistent error response format across all microservices to simplify frontend integration and error parsing.
- Security Hardening: Prevent 'Information Disclosure' vulnerabilities by automatically sanitizing error messages and hiding internal stack traces from public-facing clients.
- Production Debugging: Implement structured logging with trace IDs and request context to enable rapid root-cause analysis during system incidents.
- Refactoring Legacy Code: Replace scattered try-catch blocks with a centralized async error handler and standardized exception classes to reduce boilerplate and improve code readability.
| name | error-handling-standardizer |
|---|---|
| description | Creates consistent error handling with custom error classes, HTTP status mapping, structured logging, safe client messages, and error taxonomy. Use when standardizing "error handling", "logging", "error responses", or "exception management". |
Error Handling Standardizer
Build consistent, debuggable error handling across the application.
Error Taxonomy
export class AppError extends Error {
constructor(
public code: string,
public message: string,
public statusCode: number = 500,
public isOperational: boolean = true,
public details?: any
) {
super(message);
Error.captureStackTrace(this, this.constructor);
}
}
export class ValidationError extends AppError {
constructor(details: Record<string, string[]>) {
super("VALIDATION_ERROR", "Validation failed", 400, true, details);
}
}
export class NotFoundError extends AppError {
constructor(resource: string) {
super("NOT_FOUND", `${resource} not found`, 404);
}
}
export class UnauthorizedError extends AppError {
constructor(message = "Unauthorized") {
super("UNAUTHORIZED", message, 401);
}
}
export class ForbiddenError extends AppError {
constructor(message = "Forbidden") {
super("FORBIDDEN", message, 403);
}
}
Error Handler Middleware
export const errorHandler = (
err: Error,
req: Request,
res: Response,
next: NextFunction
) => {
// Log error
logger.error("Request error", {
error: err.message,
stack: err.stack,
path: req.path,
method: req.method,
requestId: req.id,
});
// Operational errors (known)
if (err instanceof AppError && err.isOperational) {
return res.status(err.statusCode).json({
success: false,
error: {
code: err.code,
message: err.message,
details: err.details,
trace_id: req.id,
},
});
}
// Programming errors (unknown)
return res.status(500).json({
success: false,
error: {
code: "INTERNAL_ERROR",
message: "An unexpected error occurred",
trace_id: req.id,
},
});
};
Structured Logging
import winston from "winston";
export const logger = winston.createLogger({
level: "info",
format: winston.format.combine(
winston.format.timestamp(),
winston.format.errors({ stack: true }),
winston.format.json()
),
transports: [
new winston.transports.File({ filename: "error.log", level: "error" }),
new winston.transports.File({ filename: "combined.log" }),
],
});
// Log with context
logger.error("Payment processing failed", {
userId: user.id,
amount: payment.amount,
error: err.message,
trace_id: req.id,
});
Safe Client Messages
// Never expose internal errors to clients
const getSafeErrorMessage = (err: Error): string => {
if (err instanceof AppError && err.isOperational) {
return err.message; // Safe, user-facing message
}
// Generic message for unexpected errors
return "An unexpected error occurred";
};
Async Error Handling
// Wrap async routes
export const asyncHandler = (fn: RequestHandler) => {
return (req: Request, res: Response, next: NextFunction) => {
Promise.resolve(fn(req, res, next)).catch(next);
};
};
// Usage
router.get(
"/users",
asyncHandler(async (req, res) => {
const users = await userService.findAll();
res.json(users);
})
);
Best Practices
- Use custom error classes
- Distinguish operational vs programming errors
- Log all errors with context
- Never expose stack traces to clients
- Include trace IDs for debugging
- Monitor error rates by type
- Set up alerting for critical errors
Output Checklist
- Custom error classes defined
- Error handler middleware
- HTTP status code mapping
- Structured logging setup
- Safe client error messages
- Async error wrapper
- Error monitoring/alerts
- Documentation of error codes