error-handling

Error Handling

This skill covers the architecture of error handling — not just try/catch placement, but how errors are designed, propagated, recovered from, and observed across a system.

When to Use

• Designing a new service that calls external APIs, databases, or message queues
• Reviewing code where error handling is implicit, missing, or inconsistent
• A service is experiencing cascading failures when a dependency goes down
• Adding retry logic to a flaky integration
• Designing the error response contract for an API

When NOT to Use

• Language-specific error handling syntax reference — see the relevant language skill (python, nestjs, rust)
• Frontend error boundaries — partially covered in react and vue skills
• Database-specific error handling — see sql-and-database

Core Principles

Errors are First-Class Domain Objects

An error is not an exception to be caught and discarded — it is information about what went wrong, at what level, and whether the caller can recover. Design error types with the same intentionality as domain models.

Fail Fast, Recover Intentionally

Fail immediately when a precondition is violated. Recover only from errors where you know how to recover correctly. Unknown recovery is worse than explicit failure — it produces systems that appear to work while silently degrading.

Error Propagation Has a Direction

Infrastructure errors (database down, network timeout) should not surface as-is to API consumers. Map errors at boundaries: infrastructure errors → service errors → API errors. Each layer translates, not just forwards.

Error Taxonomy

Classify every error before handling it:

Class	Description	Default Action
Transient	Temporary condition that may resolve on retry: network blip, rate limit, brief DB overload	Retry with backoff
Permanent	Will not resolve on retry: invalid input, resource not found, auth failure	Fail immediately, surface to caller
Dependency	A downstream service is unavailable or degraded	Circuit break, degrade gracefully
Programming	Bug in the code: null pointer, assertion failure, type error	Log with full context, fail loudly
Resource	Exhaustion: disk full, connection pool saturated, memory OOM	Alert immediately, do not retry silently