# StopFailure Hook

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

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** StopFailure

## Think of it like

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

## 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

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

## Example code

```json
{
  "hooks": {
    "StopFailure": [
      { "matcher": "rate_limit", "hooks": [{ "type": "command", "command": "./notify-team.sh" }] }
    ]
  }
}
```

Ping the team when a rate limit hits.

## Why it matters

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

## Common mistake

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

## Three principles

- **Instead of Stop.** On an API error.
- **Match the error.** rate_limit and more.
- **Output ignored.** Alerts only.

## Related terms

- [Stop Hook](https://learn.benibix.com/term/ai/stop-hook)
- [Notification Hook](https://learn.benibix.com/term/ai/notification-hook)

## Told apart from

- [Stop Hook vs StopFailure Hook](https://learn.benibix.com/compare/stop-hook-vs-stopfailure-hook): People think a Stop hook runs at the end of every turn, whatever happens. It only runs when Claude finishes its answer on its own. A turn cut short by an API error, such as a rate limit, fires StopFailure instead. And only Stop can send Claude back to work. StopFailure ignores what the hook prints, so it is for alerts.

---

Source: https://learn.benibix.com/term/ai/stopfailure-hook
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
