error-patterns

Table of Contents

• Overview
• When to Use
• Error Classification
• By Severity
• By Recoverability
• Quick Start
• Standard Error Handler
• Error Result
• Common Patterns
• Authentication Errors (401/403)
• Rate Limit Errors (429)
• Timeout Errors
• Context Too Large (400)
• Integration Pattern
• Detailed Resources
• Exit Criteria

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

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
• 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

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