Error Patterns

---
name: error-patterns
description: Provides error classification, recovery, and graceful-degradation patterns. Use when implementing error handling or debugging resilience failures in any skill.
alwaysApply: false
category: infrastructure
tags:
- errors
- error-handling
- recovery
- resilience
- debugging
dependencies:
- usage-logging
provides:
  infrastructure:
  - error-handling
  - error-classification
  - recovery
  patterns:
  - graceful-degradation
  - error-logging
  - debugging
usage_patterns:
- error-handling
- resilience-patterns
- debugging-workflows
complexity: beginner
model_hint: fast
estimated_tokens: 450
progressive_loading: true
modules:
- modules/classification.md
- modules/recovery-strategies.md
- modules/agent-damage-control.md
---

# Error Patterns

## Overview

Standardized error handling patterns for consistent, production-grade behavior across plugins. Provides error classification, recovery strategies, and debugging workflows.

## When To Use

- Building resilient integrations
- Need consistent error handling
- Want graceful degradation
- Debugging production issues

## When NOT To Use

- Project doesn't use the leyline infrastructure patterns
- Simple scripts without service architecture needs

## Error Classification

### By Severity

| Level | Action | Example |
|-------|--------|---------|
| **Critical** | Halt, alert | Auth failure, service down |
| **Error** | Retry or secondary strategy | Rate limit, timeout |
| **Warning** | Log, continue | Partial results, deprecation |
| **Info** | Log only | Non-blocking issues |

### By Recoverability

```python
class ErrorCategory(Enum):
    TRANSIENT = "transient"  # Retry likely to succeed
    PERMANENT = "permanent"  # Retry won't help
    CONFIGURATION = "config"  # User action needed
    RESOURCE = "resource"  # Quota/limit issue
```
**Verification:** Run the command with `--help` flag to verify availability.

## Quick Start

### Standard Error Handler
```python
from leyline.error_patterns import handle_error, ErrorCategory

try:
    result = service.execute(prompt)
except RateLimitError as e:
    return handle_error(
        e, ErrorCategory.RESOURCE, {"retry_after": e.retry_after, "service": "gemini"}
    )
except AuthError as e:
    return handle_error(
        e, ErrorCategory.CONFIGURATION, {"action": "Run 'gemini auth login'"}
    )
```
**Verification:** Run the command with `--help` flag to verify availability.

### Error Result
```python
@dataclass
class ErrorResult:
    category: ErrorCategory
    message: str
    recoverable: bool
    suggested_action: str
    metadata: dict
```
**Verification:** Run the command with `--help` flag to verify availability.

## Common Patterns

### Authentication Errors (401/403)
- Verify credentials exist
- Check token expiration
- Validate permissions/scopes
- Suggest re-authentication

### Rate Limit Errors (429)
- Extract retry-after header
- Log for quota tracking
- Implement backoff
- Consider alternative service

### Timeout Errors
- Increase timeout for retries
- Break into smaller requests
- Use async patterns
- Consider different model

### Context Too Large (400)
- Estimate tokens before request
- Split into multiple requests
- Reduce input content
- Use larger context model

## Integration Pattern

```yaml
# In your skill's frontmatter
dependencies: [leyline:error-patterns]
```
**Verification:** Run the command with `--help` flag to verify availability.

## Detailed Resources

- **Classification**: See `modules/classification.md` for error taxonomy
- **Recovery**: See `modules/recovery-strategies.md` for handling patterns
- **Agent Damage Control**: See `modules/agent-damage-control.md` for multi-agent error recovery and escalation

## Exit Criteria

- Error classified correctly
- Appropriate recovery attempted
- User-actionable message provided
- Error logged for debugging