error-patterns

athola's avatarfrom athola

Standardized error handling patterns with classification, recovery, and logging strategies.Triggers: error handling, error recovery, graceful degradation, resilienceUse when: implementing error handling in production plugins

⭐83stars🔀11forks📁View on GitHub🕐Updated Jan 3, 2026

When & Why to Use This Skill

This Claude skill provides a standardized framework for error handling, classification, and recovery strategies specifically designed for production-grade AI agents and plugins. It empowers developers to implement resilient systems with consistent logging, graceful degradation, and automated recovery workflows for common integration challenges.

Use Cases

  • 1. Resilient API Integrations: Implementing automated backoff and retry logic for handling rate limits (429) and service timeouts in external tool calls.
  • 2. Production Observability: Utilizing standardized error classification (Transient vs. Permanent) and logging to streamline debugging and monitoring of live agent deployments.
  • 3. Graceful Degradation: Designing agents that can maintain partial functionality or provide actionable user feedback during authentication failures or service outages.
  • 4. Context Management: Automatically resolving 'Context Too Large' errors by implementing intelligent request splitting and token estimation patterns.
nameerror-patterns
description|
Triggerserror handling, error recovery, graceful degradation, resilience
Use whenimplementing error handling in production plugins
categoryinfrastructure
tags[errors, error-handling, recovery, resilience, debugging]
dependencies[usage-logging]
infrastructure[error-handling, error-classification, recovery]
patterns[graceful-degradation, error-logging, debugging]
complexitybeginner
estimated_tokens450
progressive_loadingtrue

Table of Contents

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

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

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

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

@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

# 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

Exit Criteria

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

Troubleshooting

Common Issues

Command not found Ensure all dependencies are installed and in PATH

Permission errors Check file permissions and run with appropriate privileges

Unexpected behavior Enable verbose logging with --verbose flag