Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

APIエラー（レート制限、認証失敗など）によってターンが終了した際に発火するStopFailureフックイベントを追加

原文（英語） ​

Added StopFailure hook event that fires when the turn ends due to an API error (rate limit, auth failure, etc.)

概要 ​

StopFailureは、Claude CodeがAPIエラーによってターンを終了した際に発火する新しいフックイベントです。レート制限（429エラー）や認証失敗などのAPIエラーを検知し、カスタムスクリプトで自動的に対応できます。これにより、エラー時の通知や復旧処理を自動化することが可能になります。

基本的な使い方 ​

settings.jsonにフックを設定します：

json
{
  "hooks": {
    "StopFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'APIエラーが発生しました' >> ~/claude-errors.log"
          }
        ]
      }
    ]
  }
}

実践例 ​

レート制限時にSlack通知を送る ​

json
{
  "hooks": {
    "StopFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST $SLACK_WEBHOOK_URL -H 'Content-type: application/json' -d '{\"text\":\"Claude Codeでレート制限エラーが発生しました。しばらく待ってから再試行してください。\"}'"
          }
        ]
      }
    ]
  }
}

エラーログをファイルに記録する ​

bash
#!/bin/bash
# ~/scripts/claude-error-logger.sh
TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
echo "[$TIMESTAMP] Claude APIエラー発生" >> ~/claude-error-history.log
json
{
  "hooks": {
    "StopFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/scripts/claude-error-logger.sh"
          }
        ]
      }
    ]
  }
}

デスクトップ通知を表示する（macOS） ​

json
{
  "hooks": {
    "StopFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"APIエラーが発生しました。レート制限または認証の問題を確認してください。\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

注意点 ​

  • StopFailureは通常のStopフックとは別のイベントです。Stopはターンが正常に終了した際に発火し、StopFailureはAPIエラーによる異常終了時のみ発火します
  • レート制限エラー（429）の場合、Claude CodeはAPI応答のretry-afterヘッダーを参照して待機時間を決定します
  • このフック内で再度APIを呼び出すスクリプトを実行すると、無限ループになる可能性があるため注意してください（この問題はv2.1.78で修正されています）
  • フックコマンドは非同期で実行されるため、コマンドの完了をClaude Codeは待ちません

関連情報 ​