---
id: gh-error-handling-patterns
name: "error-handling-patterns"
url: https://skills.yangsir.net/skill/gh-error-handling-patterns
author: wshobson
domain: ai-software-architecture-engineering
tags: ["error-handling", "resilience", "api-design", "software-engineering", "reliability"]
install_count: 22900
rating: 4.60 (120 reviews)
github: https://github.com/wshobson/agents/tree/main/plugins/developer-essentials/skills/error-handling-patterns
---

# error-handling-patterns

> 掌握跨语言的错误处理模式，包括异常、Result 类型、错误传播和优雅降级，以构建弹性应用。在实现错误处理、设计 API 或提高应用可靠性时使用此技能，确保系统稳定运行并提供良好的调试体验，从而提升软件系统的整体质量和可维护性。

**Stats**: 22,900 installs · 4.6/5 (120 reviews)

## Before / After 对比

### 提升系统稳定性与故障恢复效率

**Before**:

缺乏统一的错误处理策略，导致生产环境频繁出现未捕获的异常，故障排查耗时且难以定位根本原因，严重影响用户体验和系统可靠性。平均故障恢复时间长达 60 分钟。

**After**:

采用标准化的错误处理模式后，系统能够优雅地处理各类异常，显著减少生产事故。故障日志清晰，调试效率大幅提升，平均故障恢复时间缩短至 10 分钟。

| Metric | Before | After | Change |
|---|---|---|---|
| 平均故障恢复时间 | 60分钟 | 10分钟 | -83% |

## Readme

# Error Handling Patterns

Build resilient applications with robust error handling strategies that gracefully handle failures and provide excellent debugging experiences.

## When to Use This Skill

- Implementing error handling in new features
- Designing error-resilient APIs
- Debugging production issues
- Improving application reliability
- Creating better error messages for users and developers
- Implementing retry and circuit breaker patterns
- Handling async/concurrent errors
- Building fault-tolerant distributed systems

## Core Concepts

### 1. Error Handling Philosophies

**Exceptions vs Result Types:**

- **Exceptions**: Traditional try-catch, disrupts control flow
- **Result Types**: Explicit success/failure, functional approach
- **Error Codes**: C-style, requires discipline
- **Option/Maybe Types**: For nullable values

**When to Use Each:**

- Exceptions: Unexpected errors, exceptional conditions
- Result Types: Expected errors, validation failures
- Panics/Crashes: Unrecoverable errors, programming bugs

### 2. Error Categories

**Recoverable Errors:**

- Network timeouts
- Missing files
- Invalid user input
- API rate limits

**Unrecoverable Errors:**

- Out of memory
- Stack overflow
- Programming bugs (null pointer, etc.)

## Detailed patterns and worked examples

Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.

## Best Practices

1. **Fail Fast**: Validate input early, fail quickly
2. **Preserve Context**: Include stack traces, metadata, timestamps
3. **Meaningful Messages**: Explain what happened and how to fix it
4. **Log Appropriately**: Error = log, expected failure = don't spam logs
5. **Handle at Right Level**: Catch where you can meaningfully handle
6. **Clean Up Resources**: Use try-finally, context managers, defer
7. **Don't Swallow Errors**: Log or re-throw, don't silently ignore
8. **Type-Safe Errors**: Use typed errors when possible

```python
# Good error handling example
def process_order(order_id: str) -> Order:
    """Process order with comprehensive error handling."""
    try:
        # Validate input
        if not order_id:
            raise ValidationError("Order ID is required")

        # Fetch order
        order = db.get_order(order_id)
        if not order:
            raise NotFoundError("Order", order_id)

        # Process payment
        try:
            payment_result = payment_service.charge(order.total)
        except PaymentServiceError as e:
            # Log and wrap external service error
            logger.error(f"Payment failed for order {order_id}: {e}")
            raise ExternalServiceError(
                f"Payment processing failed",
                service="payment_service",
                details={"order_id": order_id, "amount": order.total}
            ) from e

        # Update order
        order.status = "completed"
        order.payment_id = payment_result.id
        db.save(order)

        return order

    except ApplicationError:
        # Re-raise known application errors
        raise
    except Exception as e:
        # Log unexpected errors
        logger.exception(f"Unexpected error processing order {order_id}")
        raise ApplicationError(
            "Order processing failed",
            code="INTERNAL_ERROR"
        ) from e
```

## Common Pitfalls

- **Catching Too Broadly**: `except Exception` hides bugs
- **Empty Catch Blocks**: Silently swallowing errors
- **Logging and Re-throwing**: Creates duplicate log entries
- **Not Cleaning Up**: Forgetting to close files, connections
- **Poor Error Messages**: "Error occurred" is not helpful
- **Returning Error Codes**: Use exceptions or Result types
- **Ignoring Async Errors**: Unhandled promise rejections


---
*Source: https://skills.yangsir.net/skill/gh-error-handling-patterns*
*Markdown mirror: https://skills.yangsir.net/api/skill/gh-error-handling-patterns/markdown*