What
A new hook event type that fires when a turn ends due to an API error (rate limit, auth failure, billing error, etc.), distinct from the normal Stop event.
Usage
{
"hooks": {
"StopFailure": [
{
"type": "command",
"command": "echo 'API error: $CLAUDE_HOOK_ERROR'"
}
]
}
}Details
- Fires instead of
Stopwhen an API error ended the turn - Fire-and-forget — hook output and exit codes are ignored
- Supports matching on error type:
rate_limit,authentication_failed,billing_error,invalid_request,server_error,max_output_tokens,unknown
Evidence
Hook event definition (search for "StopFailure") — added to the hook event schema with matcherMetadata on "error" field
Strings lifted out of the shipped bundle, so the claim above can be checked against them.
One source agreesOne thing we can check says the same as this entry.
Anthropic's release notes agree
Added StopFailure hook event that fires when the turn ends due to an API error (rate limit, auth failure, etc.)