Skip to content
Skills Library
Programming · Review & audit

error-handling-patterns

/error-handling-patterns

Design and review error handling in a codebase: which errors are expected results versus bugs, typed error hierarchies or result types, where to catch (boundaries) and where never to, preserving cause chains, mapping errors to HTTP and CLI exit codes, retries with backoff for the transient, timeouts everywhere, and the logging that makes a failure diagnosable; with idioms for TypeScript, Python, Go, and Rust. Use when adding error handling to new code, when a codebase has inconsistent or swallowed errors, or when a failure in production was impossible to trace.

Repository
dotclaude ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Design and review error handling in a codebase: which errors are expected results versus bugs, typed error hierarchies or result types, where to catch (boundaries) and where never to, preserving cause chains, mapping errors to HTTP and CLI exit codes, retries with backoff for the transient, timeouts everywhere, and the logging that makes a failure diagnosable; with idioms for TypeScript, Python, Go, and Rust. Use when adding error handling to new code, when a codebase has inconsistent or swallowed errors, or when a failure in production was impossible to trace.

Arguments

/error-handling-patterns (optional) the module or the failure to design for
Original author description

Design and review error handling in a codebase: which errors are expected results versus bugs, typed error hierarchies or result types, where to catch (boundaries) and where never to, preserving cause chains, mapping errors to HTTP and CLI exit codes, retries with backoff for the transient, timeouts everywhere, and the logging that makes a failure diagnosable; with idioms for TypeScript, Python, Go, and Rust. Use when adding error handling to new code, when a codebase has inconsistent or swallowed errors, or when a failure in production was impossible to trace.

How it works

  1. First decision: expected outcome or bug?
  2. Represent errors with types
  3. Where to catch
  4. Preserve the chain
  5. Boundaries
  6. Transient failures
  7. Logging
  8. Language idioms
  9. Review checklist
Original SKILL.md headings · 61 lines, 855 words
SKILL.md preview
---
name: error-handling-patterns
description: "Design and review error handling in a codebase: which errors are expected results versus bugs, typed error hierarchies or result types, where to catch (boundaries) and where never to, preserving cause chains, mapping errors to HTTP and CLI exit codes, retries with backoff for the transient, timeouts everywhere, and the logging that makes a failure diagnosable; with idioms for TypeScript, Python, Go, and Rust. Use when adding error handling to new code, when a codebase has inconsistent or swallowed errors, or when a failure in production was impossible to trace."
argument-hint: "(optional) the module or the failure to design for"
---

Error handling has one purpose: when something goes wrong, the right party finds out, with enough context to act, and the system stays in a known state. Every pattern below is judged by that.

## First decision: expected outcome or bug?

- **Expected outcomes** (not found, validation failed, permission denied, rate limited, conflict) are part of the function's contract. Represent them in the type: a result type, a discriminated union, a documented typed error. Callers handle them.
- **Bugs and infrastructure failures** (null where impossible, invariant broken, database down, out of memory) are exceptions. They propagate to a boundary that logs them and fails the operation; code in between does not catch them.

Mixing the two (throwing for "not found", or returning null for "database down") produces both noisy logs and silent failures.

## Represent errors with types

- Base error class per domain (`AppError` with `code`, `httpStatus`, `isOperational`), subclasses for categories (`NotFoundError`, `ValidationError`, `ConflictError`, `UpstreamError`). One place maps code to status and to user message.
- Or a result type (`Result<T, E>` / `Either`) for expected outcomes in functional codebases; then errors are values, exhaustively matched, and never forgotten. Do not use both styles in one module.
- Errors carry structured context: the ids involved, the operation, the upstream status. Not the user's secrets, not whole request bodies.

## Where to catch

Catch at **boundaries**: the HTTP handler, the CLI entry, the job runner, the message consumer, the top of a background task. There, translate to the boundary's vocabulary (status code, exit code, ack/nack), log once with full context, and stop.

In between, catch only to **add context and rethrow** (`throw new UpstreamError("payments: charge failed", { cause: err, orderId })`) or to **handle an expected outcome** you can actually resolve (retry, fallback with a documented consequence, default that is semantically correct).

Never: empty catch, catch-and-log-and-continue in the middle of a flow, catch of a broad type when a narrow one was meant, catch to return a sentinel that callers do not check.

## Preserve the chain

- `new Error(msg, { cause })` in JS; `raise ... from err` in Python; `fmt.Errorf("...: %w", err)` in Go; `#[source]`/`thiserror` in Rust. The boundary logs the whole chain.
- Never convert an error to a string before it reaches the logger; never replace it with a generic one.

## Boundaries

**HTTP**: 400 validation, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict, 422 semantic, 429 rate limit, 500 unexpected (never leak the message), 502/503/504 upstream. One error response shape (RFC 9457 problem details). A 200 with `{ error }` in the body is a bug.

**CLI**: exit 0 success, 1 general failure, 2 usage error, others per convention; message to stderr, machine output to stdout; `--verbose` for the chain.

**Jobs and consumers**: distinguish retryable (nack with delay, bounded attempts, then dead-letter with the error attached) from poison (dead-letter immediately). Idempotent handlers so retries are safe.

**Background tasks and event handlers**: an unhandled rejection in a fire-and-forget task must still reach the logger and the process's error metric; wrap the entry in a handler.

## Transient failures

- Timeouts on every outbound call (HTTP, DB, queue), shorter than the caller's own timeout. A missing timeout is an error that presents as a hang.
- Retry only idempotent operations and only for transient classes (connection reset, 503, 429 with `Retry-After`), with exponential backoff and jitter, a small maximum (3), and a total budget. Log each retry at debug, the final failure at error.
- Circuit breaker when a dependency is failing at volume, so the system degrades instead of piling up timeouts.
- Fallbacks must be documented consequences: "serve cached price, flag stale" is a fallback; "return 0" is a silent failure.

## Logging

Log once, at the boundary, at error level, with: the error class and message, the chain, the operation, the ids, the correlation/request id, and duration. Log expected outcomes (404, validation) at info or not at all; they are not incidents. Never log secrets, tokens, or full bodies. Count errors by class in a metric so a spike is visible.

## Language idioms

- **TypeScript**: `catch (err: unknown)` then narrow (`err instanceof AppError`); `Promise.allSettled` when partial failure is acceptable, `Promise.all` when one failure should fail all; no floating promises (`await` or `void` with a handler); `AbortSignal.timeout(ms)` for fetch.
- **Python**: catch specific exceptions, never bare `except:`; `raise ... from`; `contextlib` for cleanup; `asyncio.timeout()`; `logging.exception()` at the boundary.
- **Go**: return errors, wrap with `%w`, check with `errors.Is`/`errors.As`; sentinel errors for expected outcomes; `context.WithTimeout` on every call; never ignore a returned error (`_ =` needs a comment).
- **Rust**: `Result` everywhere, `?` to propagate, `thiserror` for library errors, `anyhow` at binaries; `expect` only for invariants with a message that says why it cannot fail.

## Review checklist

Every catch either rethrows with context, handles an expected outcome, or is at a boundary. No error is stringified early. Every outbound call has a timeout. Retries are bounded and idempotent. Boundaries return the right status. Logs at the boundary carry the chain and the ids. Tests cover each expected outcome and at least one unexpected failure path (`test-gap-analyzer` will check).

Versions

RepositoryScoreLicence
This page · khaledsaeed18/dotclaude90MIT
event4u-app/agent-config100MIT
rootcastleco/rei-skills100MIT
JayRHa/AgentSkills100MIT
wshobson/agents100MIT
erichowens/some_claude_skills98MIT
HermeticOrmus/LibreUIUX-Claude-Code95MIT
wesleyegberto/software-engineering-skills95MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 6119fe2ad7eb (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100error-handling
    Language-neutral error handling. Classifying failures, where to catch, typed errors, propagating with context, API error responses, logging once, user vs developer messages, timeouts, retries with backoff, circuit breakers and fallbacks. Use when designing error types, adding…
  • 90handling-errors
    Rules for errors - Result vs throw, retries, the ERRORS catalog, hints, exit codes, boundary catches, one shape over HTTP, CLI and MCP. Use when you add or change an error code, hint, exit code or catch, or review such a diff. Don't use for an operation's error list (use working-with-contracts).
  • 100error-handling
    Patterns for robust error handling across TypeScript, Python, and Go. Covers typed errors, error boundaries, retries, circuit breakers, and user-facing error messages. Use when designing error types, retries, circuit breakers, or user-facing failure messages in TypeScript, Python, or Go.
  • 100error-handling
    Patterns for robust error handling across TypeScript, Python, and Go. Covers typed errors, error boundaries, retries, circuit breakers, and user-facing error messages. Use when designing error types, retries, circuit breakers, or user-facing failure messages in TypeScript, Python, or Go.
  • 100error-code-guide
    Design consistent error codes following the PREFIX_CATEGORY_NUMBER format. Use when: defining error codes, creating error handling, designing APIs. Not for: log format and levels — use /logging-guide; handling errors that already reached production — use /incident. Keywords:…
  • 95rust-error-handling
    Use when Rust error handling with Result, Option, custom errors, thiserror, and anyhow. Use when handling errors in Rust applications.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.