Skip to content
BENIBIX Learn

StopFailure Hook

AI⌨️ Claude CodeConfiguration

Also known as StopFailure

The event when a turn ends on an error. It is for logs and alerts.

Think of it like

It is like a smoke alarm. It cannot put the fire out, but it tells you.

Example

Jack's long overnight job hit a rate limit. His StopFailure hook sent him a phone alert, so he knew by breakfast.

Why it matters

A failed turn is silent if no one is watching. This makes it loud.

Definition

StopFailure is the hook event that fires instead of Stop when a turn ends because of an API error. Examples are a rate limit, an overloaded server or a login problem. The matcher can pick the kind of error. Claude Code ignores what the hook prints, so it is for logging and alerts only.

Example code

json
{
  "hooks": {
    "StopFailure": [
      { "matcher": "rate_limit", "hooks": [{ "type": "command", "command": "./notify-team.sh" }] }
    ]
  }
}
Ping the team when a rate limit hits.

Common mistake

Trying to make Claude retry from here. The output is ignored, so it cannot steer anything.

Key takeaways

  1. 1
    Instead of Stop. On an API error.
  2. 2
    Match the error. rate_limit and more.
  3. 3
    Output ignored. Alerts only.

Compare