API エラーで中断した時にフックを実行したい
11. フックコマンド / 機能
StopFailureエラー終了時フック
概要
StopFailure フックは Claude のターンが API エラー（レート制限・タイムアウトなど）で終了した時に発火します。エラー通知やリトライ処理の実装に使います。
設定例
// .claude/settings.json
{
"hooks": {
"StopFailure": [
{
"type": "command",
"command": "notify-send 'Claude Code' 'APIエラーが発生しました'"
}
]
}
}
// エラー内容を含む通知の例
#!/bin/bash
# $CLAUDE_HOOK_DATA に JSON で情報が入る
error_msg=$(echo "$CLAUDE_HOOK_DATA" | jq -r '.error // "不明なエラー"')
notify-send "Claude Code エラー" "$error_msg"こんな時に使う
- API エラー発生時にデスクトップ通知したい時
- エラーをログに記録したい時
- 障害検知・アラートを実装したい時
使い方
- 1hooks.StopFailure にフックを定義
- 2通常の Stop フックと同様に command/http/prompt/agent が使える
- 3CLAUDE_HOOK_DATA 環境変数でエラー情報を取得
Tips
- Stop（正常終了）と StopFailure（エラー終了）は別イベント
- レート制限・タイムアウト・ネットワークエラーで発火
- エラー情報は JSON 形式で CLAUDE_HOOK_DATA に渡される