error-patterns

エラーパターン

概要

プラグイン間で一貫性のある、本番環境に適した動作を実現するための標準化されたエラー処理パターンです。エラーの分類、復旧戦略、デバッグのワークフローを提供します。

使用する場面

• レジリエントな統合を構築する場合
• 一貫したエラー処理が必要な場合
• 適切な縮退運転を実現したい場合
• 本番環境の問題をデバッグする場合

使用しない場面

• プロジェクトで leyline のインフラストラクチャパターンを使用していない場合
• サービスアーキテクチャを必要としない単純なスクリプトの場合

エラーの分類

重大度別

レベル	対応	例
Critical	停止して通知	認証の失敗、サービスの停止
Error	再試行または代替戦略	レート制限、タイムアウト
Warning	ログに記録して続行	部分的な結果、非推奨化
Info	ログにのみ記録	処理を妨げない問題

復旧可能性別

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

確認： コマンドに --help フラグを指定して実行し、利用可能であることを確認します。

クイックスタート

標準エラーハンドラー

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 フラグを指定して実行し、利用可能であることを確認します。

エラー結果

@dataclass
class ErrorResult:
    category: ErrorCategory
    message: str
    recoverable: bool
    suggested_action: str
    metadata: dict

確認： コマンドに --help フラグを指定して実行し、利用可能であることを確認します。

よくあるパターン

認証エラー（401/403）

• 認証情報が存在することを確認する
• トークンの有効期限を確認する
• 権限／スコープを検証する
• 再認証を提案する

レート制限エラー（429）

• retry-after ヘッダーを抽出する
• クォータ追跡用にログを記録する
• バックオフを実装する
• 代替サービスを検討する

タイムアウトエラー

• 再試行時のタイムアウトを延長する
• リクエストを小さく分割する
• 非同期パターンを使用する
• 別のモデルを検討する

コンテキストが大きすぎる（400）

• リクエスト前にトークン数を推定する
• 複数のリクエストに分割する
• 入力内容を減らす
• より大きなコンテキストに対応したモデルを使用する

統合パターン

# In your skill's frontmatter
dependencies: [leyline:error-patterns]

確認： コマンドに --help フラグを指定して実行し、利用可能であることを確認します。

詳細リソース

• 分類：エラー分類体系については modules/classification.md を参照してください
• 復旧：処理パターンについては modules/recovery-strategies.md を参照してください
• エージェントのダメージコントロール：マルチエージェントのエラー復旧とエスカレーションについては modules/agent-damage-control.md を参照してください

完了条件

• エラーが正しく分類されている
• 適切な復旧を試みている
• ユーザーが対応できるメッセージを提示している
• デバッグ用にエラーをログに記録している