Feature request: hook event for API transport/server errors (502/5xx/429/529)

Summary

Add a hook event that fires when Claude Code hits an API transport/server error (e.g. 502 Bad Gateway, other 5xx, 429, 529 overloaded) — i.e. the request to the Anthropic API itself fails, independent of any tool call.

This is distinct from the already-shipped tool-failure hooks (PostToolUseError / PostToolUseFailure, see #15346 / #4366). Those fire when a tool errors. They do not fire on a raw API transport failure, which can happen with no tool call in flight (e.g. mid-stream, or on the very first model turn).

Related prior request #21168 was closed as "PostToolUseError already covers this", but that conflates tool-execution errors with API transport errors. The 502 case is still uncovered.

Problem

When the API returns 502 Bad Gateway (server-side), the client surfaces only a UI error banner. No hook fires:

• PostToolUse / PostToolUseError — no tool was executing
• Stop — the conversation didn't end cleanly
• Notification — not triggered for API transport errors
• UserPromptSubmit — user hasn't typed

In the Desktop app there is effectively no way to be notified other than visually noticing the banner. For autonomous / long-running sessions this means a 502 can silently stall the run until a human happens to look.

The information needed to fire a hook already exists locally: the client clearly knows the request failed with 502 (it renders the banner). So a hook dispatch on the client's API-error handling path is straightforward.

Proposed Solution

A new hook event (name TBD — OnApiError / RequestFailed) that fires from the client-side error handler:

{
  "hooks": {
    "OnApiError": [
      { "matcher": "5xx|429|529", "hooks": [{ "type": "command", "command": "notify-me.sh" }] }
    ]
  }
}

Suggested payload (stdin JSON):

• HTTP status code (e.g. 502)
• error message / type
• retry attempt count (if auto-retry is in progress)
• whether a tool call was in flight (and which)
• session id

Use Cases

1. Notify on stall — fire a desktop/Slack notification so the user knows the session died, instead of discovering it minutes later.
2. Autonomous recovery — orchestration/watchdog workflows can react (re-trigger, /rewind, escalate) instead of polling for error text.

Why existing hooks don't cover it

| Hook | Fires on 502 transport error? |
|---|---|
| PostToolUse / PostToolUseError | No — requires a tool execution |
| Stop / SubagentStop | No — only clean conversation end |
| Notification | No — not wired for API transport errors |
| UserPromptSubmit | No |

Additional Context

Encountered in the wild as a plain API Error: 502 Bad Gateway. This is a server-side issue... banner with no programmatic surface to hook into.