api-error-handling

Implements standardized API error responses with proper status codes, logging, and user-friendly messages. Use when building production APIs, implementing error recovery patterns, or integrating error monitoring services.

⭐9stars🔀0forks📁View on GitHub🕐Updated Jan 1, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for implementing standardized API error handling and resilient communication patterns. It offers ready-to-use error response structures, specialized exception classes for Node.js and Python, and advanced reliability patterns like Circuit Breakers to ensure production-grade stability and a superior developer experience.

Use Cases

  • Standardizing error response formats across multiple microservices to ensure consistent client-side error handling and integration.
  • Implementing robust logging and request traceability using Request IDs to significantly reduce the Mean Time to Repair (MTTR) during production incidents.
  • Enhancing system resilience by deploying the Circuit Breaker pattern to prevent cascading failures when downstream services or third-party APIs are unresponsive.
  • Improving API security and user experience by masking internal stack traces while providing clear, actionable, and user-friendly error messages to end-users.
nameapi-error-handling
descriptionImplements standardized API error responses with proper status codes, logging, and user-friendly messages. Use when building production APIs, implementing error recovery patterns, or integrating error monitoring services.

API Error Handling

Implement robust error handling with standardized responses and proper logging.

Standard Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "status": 400,
    "requestId": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z",
    "details": [
      { "field": "email", "message": "Invalid email format" }
    ]
  }
}

Error Class (Node.js)

class ApiError extends Error {
  constructor(code, message, status = 500, details = null) {
    super(message);
    this.code = code;
    this.status = status;
    this.details = details;
  }

  static badRequest(message, details) {
    return new ApiError('BAD_REQUEST', message, 400, details);
  }

  static notFound(resource) {
    return new ApiError('NOT_FOUND', `${resource} not found`, 404);
  }

  static unauthorized() {
    return new ApiError('UNAUTHORIZED', 'Authentication required', 401);
  }
}

// Global error handler
app.use((err, req, res, next) => {
  const status = err.status || 500;
  const response = {
    error: {
      code: err.code || 'INTERNAL_ERROR',
      message: status === 500 ? 'Internal server error' : err.message,
      status,
      requestId: req.id
    }
  };

  if (err.details) response.error.details = err.details;
  if (status >= 500) logger.error(err);

  res.status(status).json(response);
});

Circuit Breaker Pattern

class CircuitBreaker {
  constructor(threshold = 5, timeout = 30000) {
    this.failures = 0;
    this.threshold = threshold;
    this.timeout = timeout;
    this.state = 'CLOSED';
  }

  async call(fn) {
    if (this.state === 'OPEN') throw new Error('Circuit open');
    try {
      const result = await fn();
      this.failures = 0;
      return result;
    } catch (err) {
      this.failures++;
      if (this.failures >= this.threshold) {
        this.state = 'OPEN';
        setTimeout(() => this.state = 'HALF_OPEN', this.timeout);
      }
      throw err;
    }
  }
}

Additional Implementations

See references/python-flask.md for:

  • Python Flask error handling with custom exceptions
  • Circuit breaker with automatic recovery
  • Retry with exponential backoff
  • Sentry integration

Best Practices

  • Use consistent error format across all endpoints
  • Include request IDs for traceability
  • Log errors at appropriate severity levels
  • Never expose stack traces to clients
  • Distinguish client errors (4xx) from server errors (5xx)
  • Provide actionable error messages