Back to Details

error-patterns

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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
  • 构建高韧性集成系统
  • 需要统一的错误处理逻辑
  • 希望实现优雅降级
  • 排查生产环境问题

When NOT To Use

不适用场景

  • Project doesn't use the leyline infrastructure patterns
  • Simple scripts without service architecture needs
  • 项目未使用leyline基础设施模式
  • 无服务架构需求的简单脚本

Error Classification

错误分类

By Severity

按严重程度划分

LevelActionExample
CriticalHalt, alertAuth failure, service down
ErrorRetry or secondary strategyRate limit, timeout
WarningLog, continuePartial results, deprecation
InfoLog onlyNon-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.
python
class ErrorCategory(Enum):
    TRANSIENT = "transient"      # 重试大概率成功
    PERMANENT = "permanent"       # 重试无效
    CONFIGURATION = "config"      # 需要用户操作
    RESOURCE = "resource"         # 配额/限制问题
验证方式： 运行带
--help
参数的命令验证功能是否可用。

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.
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'"
    })
验证方式： 运行带
--help
参数的命令验证功能是否可用。

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.
python
@dataclass
class ErrorResult:
    category: ErrorCategory
    message: str
    recoverable: bool
    suggested_action: str
    metadata: dict
验证方式： 运行带
--help
参数的命令验证功能是否可用。

Common Patterns

通用模式

Authentication Errors (401/403)

认证错误 (401/403)

  • Verify credentials exist
  • Check token expiration
  • Validate permissions/scopes
  • Suggest re-authentication
  • 验证凭证是否存在
  • 检查令牌是否过期
  • 校验权限/作用域
  • 建议重新认证

Rate Limit Errors (429)

限流错误 (429)

  • Extract retry-after header
  • Log for quota tracking
  • Implement backoff
  • Consider alternative service
  • 提取retry-after头信息
  • 记录日志用于配额追踪
  • 实现退避重试机制
  • 考虑切换备选服务

Timeout Errors

超时错误

  • Increase timeout for retries
  • Break into smaller requests
  • Use async patterns
  • Consider different model
  • 增加重试的超时时间
  • 拆分为更小的请求
  • 使用异步模式
  • 考虑切换其他模型

Context Too Large (400)

上下文过大 (400)

  • Estimate tokens before request
  • Split into multiple requests
  • Reduce input content
  • Use larger context model
  • 请求前预估token数量
  • 拆分为多个请求
  • 减少输入内容
  • 使用更大上下文的模型

Integration Pattern

集成模式

yaml
undefined
yaml
undefined

In your skill's frontmatter

在你的skill的前置配置中

dependencies: [leyline:error-patterns]
**Verification:** Run the command with `--help` flag to verify availability.
dependencies: [leyline:error-patterns]
**验证方式：** 运行带`--help`参数的命令验证功能是否可用。

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
  • 分类： 查看
    modules/classification.md
    了解错误分类体系
  • 恢复： 查看
    modules/recovery-strategies.md
    了解处理模式
  • Agent损害控制： 查看
    modules/agent-damage-control.md
    了解多Agent错误恢复与升级流程

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
命令未找到 确保所有依赖已安装且位于PATH中
权限错误 检查文件权限，使用合适的权限运行
意外行为 添加
--verbose
参数启用详细日志