api-error-handling_skill

Overview

This skill implements standardized API error responses with proper status codes, structured payloads, and integrated logging. It provides a reusable ApiError class, a global error handler, and optional resilience patterns like a circuit breaker for production-ready TypeScript/Node APIs. Use it to make errors predictable, traceable, and safe to return to clients.

How this skill works

The skill defines an ApiError class to represent domain and HTTP errors with code, message, status, requestId, timestamp, and optional details. A global Express-style error handler formats responses, attaches request IDs, hides internal stack traces, and logs server-side failures. A simple CircuitBreaker class is included to stop repeated downstream failures and allow recovery after a timeout.

When to use it

• Building production REST or GraphQL APIs
• Standardizing error payloads across services
• Integrating error monitoring (Sentry, Datadog)
• Implementing resiliency for external service calls
• Differentiating client (4xx) vs server (5xx) errors

Best practices

• Always return a consistent error JSON shape with code, message, status, requestId, and optional details.
• Attach a unique requestId to every request for tracing across logs and services.
• Log 5xx errors at error/fatal level and 4xx at warn/info as appropriate; never expose stack traces to clients.
• Use specific ApiError factory methods (badRequest, notFound, unauthorized) to keep handlers concise.
• Combine circuit breaker and retry patterns but avoid retries for idempotency-unsafe operations.

Example use cases

• Validate incoming payloads and return BAD_REQUEST with details per-field for client fixes.
• Wrap downstream API calls with CircuitBreaker to prevent cascading failures during outages.
• Throw ApiError.notFound for missing resources and ensure 404 responses include a requestId for support.
• Capture 5xx errors with logger and send enriched events to Sentry including requestId and user context.
• Return user-friendly messages for authentication/authorization failures while logging full context internally.