Skip to content
Skills Library
Programming · Planning

error-handling-patterns

/error-handling-patterns

Use when picking a failure-reporting strategy — exceptions vs Result types, recoverable vs not, retry / circuit-breaker / graceful degradation — decision framework only, catalogues externalized.

Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 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.
Content35 / 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
11
Deprecation

No signals detected. Repository changed on 26.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

Use when picking a failure-reporting strategy — exceptions vs Result types, recoverable vs not, retry / circuit-breaker / graceful degradation — decision framework only, catalogues externalized.

Original author description

Use when picking a failure-reporting strategy — exceptions vs Result types, recoverable vs not, retry / circuit-breaker / graceful degradation — decision framework only, catalogues externalized.

How it works

  1. When to use
  2. Decision framework
  3. Procedure: Apply the framework to a new feature
  4. Output format
  5. Gotcha
  6. Do NOT
  7. Auto-trigger keywords
  8. Provenance
Original SKILL.md headings · 136 lines, 1,135 words
SKILL.md preview
---
model_tier: medium
name: error-handling-patterns
description: "Use when picking a failure-reporting strategy — exceptions vs Result types, recoverable vs not, retry / circuit-breaker / graceful degradation — decision framework only, catalogues externalized."
domain: engineering
status: active
refresh_trigger: "≥30% of cited upstream pattern catalogues become deprecated, OR a new top-2 ecosystem (Python/JS/PHP/Go/Rust) ships a paradigm-shifting standard error model"
sunset_criterion: "When the upstream framework docs (Laravel, FastAPI, Express, Axum, Effect-TS) all carry an equivalent in-tree decision framework AND consumer projects no longer cite this skill in PR reviews for two consecutive review cycles."
workspaces:
  - engineering
packs:
  - engineering-base
---

# error-handling-patterns

Decision framework for picking an error-handling strategy. **Catalogues of language-specific code live upstream** (links in § Provenance) — this skill is the predicate, not the pattern library. Sunset-policy compliant: large language-specific catalogues stay in authoritative upstream docs.

## When to use

- Designing how a new feature, API, or service reports failure.
- Reviewing a diff that introduces a new exception class, `Result<T, E>`, or sentinel return.
- Debugging production noise that traces back to inconsistent error semantics.
- Choosing between retry, circuit-breaker, fallback, and fail-fast for an external dependency.

Do NOT use when:

- You only need the syntax for a `try/catch` in language X — read the upstream language guide directly.
- The failure is a single-call Laravel validation error — route to [`laravel-validation`](../laravel-validation/SKILL.md).
- The fix is a one-line null check in existing code — route to [`bug-analyzer`](../bug-analyzer/SKILL.md).

## Decision framework

### Step 1 — Classify the failure

```
Failure is:
  caller's fault (bad input, missing auth)         → reject at boundary, structured error
  expected operational (timeout, 404, rate-limit)  → Result-type / typed return; retry-aware
  unexpected operational (DB down, OOM, deadlock)  → exception; observability + alert
  programmer bug (null deref, off-by-one)          → crash early; do not catch
```

### Step 2 — Pick the reporting mechanism

```
IF failure is an EXPECTED, branchable outcome the caller will route on
  → Result type / tagged union / typed error return.
  Forces the caller to handle it; the type system is the proof.

IF failure is UNEXPECTED and most callers cannot do anything useful
  → exception, propagated to a single boundary handler.
  One layer (HTTP, queue, CLI) translates exceptions to user-facing errors.

IF failure is UNRECOVERABLE (invariant violated, data corruption)
  → fail loud, fail fast. No catch-and-continue.
  Log structured context, exit / panic / 500.

IF the language idiom forces one choice (Go: errors are values; Rust: Result;
   Python/PHP/JS: exceptions)
  → follow the idiom. Inventing a foreign mechanism is more cost than the
    correctness it buys.
```

### Step 3 — Pick the resilience strategy

```
External call?
  Idempotent + transient failure mode  → retry with exponential backoff + jitter, cap.
  Non-idempotent                       → no blind retry; require an idempotency key.
  Repeated failure across instances    → circuit breaker; open → half-open probe → close.
  Optional functionality               → graceful degradation (cached / default / null result).
  Required functionality               → propagate; surface to user with a recovery hint.
```

### Step 4 — Shape the error payload

Every produced error must carry: `code` (stable string), `message` (human-readable), `cause` (chained), `context` (sanitized inputs), `correlation_id` (request / trace).

Forbidden: secrets, raw SQL, full stack traces in user-facing surfaces, internal class names leaked through API boundaries.

**"User-facing" means PRODUCTION, and the missing half of that sentence cost a real failure.** Read without the qualifier — as it stood until 2026-09-11 — this clause forbids the developer's own diagnostics in their own dev environment, which is the opposite of what it is for. The measured consequence, reported by the maintainer: a feature whose detail view crashed on open and showed a blank region, so neither the developer nor the agent could see *what* was missing, and the failure had to be reconstructed by hand.

| Environment | What a failed render or request shows |
|---|---|
| local / dev / preview | the **full** diagnostic, visibly: what was expected, what arrived, which field or endpoint, the stack. A toast, an error overlay, an inline panel — anything the developer cannot miss. Silence here is the defect. |
| production | the sanitized payload above, plus a correlation id the developer can look up. Never the stack. |

**A blank page is never an acceptable failure mode in dev.** If a component cannot render because data is missing or a contract changed, it says so on screen in dev and degrades to a stated empty/error state in production — never to nothing. That is the same obligation the four completeness rows in [`ai-code-blindspots`](../ai-code-blindspots/SKILL.md) put on the render surface, stated here for the error path that reaches it.

### Step 5 — Define the boundary

Exactly **one** layer translates internal errors to the egress format (HTTP status + body, queue requeue policy, CLI exit code). Anywhere else doing this duplication is the bug.

## Procedure: Apply the framework to a new feature

1. **Inspect** the feature surface — identify every failure mode (each external call, each invariant, each user input class) and write it down.
2. Run Step 1 of the decision framework against each entry; write the classification next to it.
3. Pick reporting mechanism per Step 2; reject combinations the language idiom rejects.
4. For each external call, run Step 3 and write down the chosen resilience strategy.
5. Sketch the error payload shape (Step 4) and the single boundary (Step 5).
6. Hand the sketch to a reviewer **before** coding; cite this skill.

## Output format

1. The failure-mode table (mode · classification · mechanism · resilience strategy).
2. The shared error payload definition (code, message, cause, context, correlation_id).
3. The single boundary handler (file:line) where internal → egress translation happens.
4. The retry / circuit-breaker config (attempts, base, jitter, breaker thresholds), if any.

## Gotcha

- "Catch everything, log it, return null" silently destroys signal — every catch must either rethrow, translate, or recover with a written reason.
- Retries on non-idempotent calls are the second-most-common production incident; insist on idempotency keys before allowing retry.
- Circuit breakers without a half-open probe never close — they degrade to permanent failure.
- Mixing Result types and exceptions in the same module is worse than picking the wrong one — pick one per module and stay in it.
- Upstream pattern catalogues drift; trust the link, not memory. Refresh per `refresh_trigger` above.

## Do NOT

- Do NOT introduce a custom error mechanism that fights the language idiom.
- Do NOT swallow exceptions — every catch has a written purpose.
- Do NOT leak stack traces, secrets, or internal class names across the boundary.
- Do NOT retry without backoff + jitter + cap.
- Do NOT inline language-specific code catalogues into this skill — externalize per Sunset Policy.

## Auto-trigger keywords

- error handling strategy
- exceptions vs result
- retry pattern
- circuit breaker
- graceful degradation
- error payload shape

## Provenance

- Adopted from: an external reference (internal provenance, redacted) — **Sunset Policy applied**: a large source reduced to a ~150-line decision framework; language catalogues externalized to the upstream resources below.
- Externalized catalogues:
  - Python: https://docs.python.org/3/tutorial/errors.html · https://docs.python.org/3/library/exceptions.html
  - PHP / Laravel: https://laravel.com/docs/errors · https://www.php.net/manual/en/language.exceptions.php
  - JS / TS: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Control_flow_and_error_handling · https://www.typescriptlang.org/docs/handbook/2/narrowing.html
  - Go: https://go.dev/blog/error-handling-and-go · https://pkg.go.dev/errors
  - Rust: https://doc.rust-lang.org/book/ch09-00-error-handling.html
  - Resilience patterns: https://martinfowler.com/bliki/CircuitBreaker.html · https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
- Cross-linked: [`defense-in-depth`](../defense-in-depth/SKILL.md), [`laravel-validation`](../laravel-validation/SKILL.md), [`bug-analyzer`](../bug-analyzer/SKILL.md), [`api-design`](../api-design/SKILL.md).
- Provenance registry: `agents/settings/contexts/skills-provenance.yml` (entry: `error-handling-patterns`).
- Iron-Law floor: `verify-before-complete`, `skill-quality`, `non-destructive-by-default`.

Versions

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

Database snapshot: 13.11.2026 · package version 75aae69b02e0 (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-resilience
    Build resilient systems with proper error handling, retry patterns, circuit breakers, graceful degradation, and timeout management. Use when implementing API calls, database connections, external service integrations, background jobs, or any code that can fail. Also use when the…
  • 100error-handling
    Designs typed, observable, recoverable error handling - an explicit taxonomy of retryable vs terminal failures, Result types at boundaries, single-point logging, and retry policies with real backoff numbers. Use when someone asks "should I retry this error", "how do I structure…
  • 100reliability
    This skill should be used when designing, planning, implementing, or reviewing any non-trivial change, or when the user asks to "add retries", "add error handling", "add circuit breaker", "handle failures" — enforces graceful degradation, proper error handling, retry strategies,…
  • 100circuit-breaker-setup
    Configure circuit breaker setup operations. Auto-activating skill for API Integration. Triggers on: circuit breaker setup, circuit breaker setup Part of the API Integration skill category. Use when working with circuit breaker setup functionality. Trigger with phrases like…
  • 100rs-domain-error
    Use when designing domain error handling. Keywords: domain error, error categorization, recovery strategy, retry, fallback, domain error hierarchy, user-facing vs internal errors, error code design, circuit breaker, graceful degradation, resilience, error context, backoff, retry…
  • 100supabase-reliability-patterns
    Build resilient Supabase integrations: circuit breakers wrapping createClient calls, offline queue with IndexedDB, graceful degradation with cached fallbacks, health check endpoints, retry with exponential backoff and jitter, and dual-write patterns for critical data. Use when…

Feedback and reports

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