error-handling

Convert internal exceptions into structured API error responses with typed error taxonomy.

Updated Mar 20, 2026
One-click install
npx skills add https://github.com/hendrax5/ironman --skill error-handling-hendrax5
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: error-handling
Source: https://github.com/hendrax5/ironman/tree/main/skills/error-handling
Command: npx skills add https://github.com/hendrax5/ironman --skill error-handling-hendrax5

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill enforces a consistent, safe approach to mapping internal exceptions into structured API error responses, preventing leaked stack traces and inconsistent status codes.

Core Features & Use Cases

  • Typed Error Taxonomy: A hierarchical AppError base with Domain, Infra, and Auth subclasses mapped to canonical HTTP status codes.
  • Centralized Middleware: A single error-handler middleware that distinguishes operational vs programming errors, logs with traceId, and returns consistent JSON responses.
  • Layered Patterns & Rules: Best-practice guidance for controllers, services, and repositories including when to throw typed errors and how to wrap infrastructure failures.
  • Use Case: In a microservice API, use the taxonomy to convert validation failures to 422, not-found to 404, DB faults to DatabaseError with 503, and ensure clients never receive stack traces.

Quick Start

Implement the AppError hierarchy, throw typed errors in services and repositories, and register the centralized error-handler middleware so all routes forward exceptions and clients receive consistent JSON error responses.

Frequently Asked Questions about error-handling

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I convert internal exceptions into structured API error responses?

To convert internal exceptions into structured API error responses, implement a typed AppError hierarchy and register centralized error-handler middleware that maps operational errors to canonical HTTP status codes and returns consistent JSON.

How do I prevent stack traces from leaking in API error responses?

Preventing stack traces from leaking in API error responses requires centralized error-handler middleware that distinguishes operational from programming errors, suppressing stack traces in client-facing JSON output while logging full details with traceId internally.

What is the best way to map domain and infrastructure exceptions to HTTP status codes?

The best way to map domain and infrastructure exceptions to HTTP status codes is using a hierarchical AppError taxonomy with Domain, Infra, and Auth subclasses, mapping validation failures to 422, not-found to 404, and database faults to 503.

Does centralized error-handler middleware work for microservices and API gateways?

Yes, centralized error-handler middleware works for microservices and API gateways by applying layered patterns across controllers, services, and repositories to ensure consistent error formatting and traceability across distributed backend services.

When should I throw typed errors in service and repository layers?

Throw typed errors in service and repository layers when wrapping infrastructure failures or encountering operational errors, allowing the centralized middleware to distinguish them from programming errors and apply the correct HTTP status mapping.

Why do my API endpoints return inconsistent HTTP status codes for similar errors?

API endpoints return inconsistent HTTP status codes for similar errors when lacking a centralized error-handler middleware with a typed AppError taxonomy that enforces canonical HTTP status mapping and suppresses internal stack traces in client responses.