The Nightly Claude Job Died on One Busy Minute. Let It Wait, With a Ceiling.

At a glance

• Set CLAUDE_CODE_RETRY_WATCHDOG=1 and an unattended Claude Code run waits out 429 and 529 capacity errors instead of failing when its retries run out.
• Since v2.1.295, CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS caps that wait, so a CI job can't hang forever.
• At 7:04 AM ET on Tuesday 13 October, the watchdog was on every npm channel, but the cap was only on latest and next (v2.1.296), not stable (v2.1.287).

Your nightly Claude Code job ran fine for weeks, then died at 2 AM with "Repeated 529 Overloaded errors" because the API was busy for a few minutes. Claude Code has a documented retry mode for unattended runs, and since v2.1.295 you can cap how long it waits.

Why it matters

By default, Claude Code retries a failed API request 10 times (CLAUDE_CODE_MAX_RETRIES, capped at 15) and then gives up. A person at the keyboard can check status.claude.com or switch models with /model. A CI job has nobody to do that, so a short capacity spike becomes a red build.

Anthropic's docs say a 529 means the API is at capacity across all users, that it is usually temporary, and that it doesn't count against your quota. Waiting is often right, but the wait mode has no limit on its own.

Set to 1, CLAUDE_CODE_RETRY_WATCHDOG retries 429 and 529 capacity errors indefinitely, backing off up to 5 minutes between attempts, per the environment variables reference. It is off unless you set it. On v2.1.199 or later it also lifts the retry count for other transient errors, such as timeouts and dropped connections, to 300, which the docs put at roughly three hours of backoff.

Two limits keep it honest. A standard-speed request that gets a 429 for a spend limit or exhausted usage credits still fails at once, so the watchdog won't quietly wait on a capped budget. And CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS sets the most time each API request spends waiting out 429 and 529 errors. Once that time is used up, the next such error ends the request. Left unset, there is no limit.

How to give an unattended job a retry ceiling

At 7:04 AM ET on Tuesday 13 October 2026, npm stable was v2.1.287 and latest and next were v2.1.296.

1. In the job, run claude --version. The watchdog needs v2.1.186 or later, so every current npm channel has it. The ceiling needs v2.1.295 or later, so a runner that installs from stable gets the watchdog without the ceiling.
2. Set both variables in the job's environment before the step that runs Claude Code. The ceiling takes whole milliseconds in plain digits, such as 1800000 for 30 minutes.
3. On a stable runner, keep your CI system's own step timeout as the real ceiling until stable reaches v2.1.295. We suggest keeping it on latest runners too, as a backstop.
4. Our own advice: keep the watchdog out of your interactive shell profile. At the keyboard, the default retries plus /model usually get you working sooner than an open-ended wait.

We have not run this script end to end on every platform, so test it in one job before you roll it out. The prompt in the last line is only an example.

#!/usr/bin/env bash
set -eu

# Install, pick one channel (pointers checked 7:04 AM ET Tue 13 Oct 2026):
# stable channel, v2.1.287, watchdog only, no ceiling:
# npm install -g @anthropic-ai/claude-code@stable
# latest channel, v2.1.296, watchdog plus ceiling, pinned:
# npm install -g @anthropic-ai/claude-code@2.1.296

claude --version

export CLAUDE_CODE_RETRY_WATCHDOG=1
# Ceiling needs v2.1.295 or later.
export CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000

env | grep '^CLAUDE_CODE_RETRY_WATCHDOG'

# Example prompt only. Replace with your job's real task.
claude -p "Run the test suite and summarize any failures"

To verify, read the filtered env lines in the job log and confirm both variables are set before Claude Code starts, and check that claude --version printed v2.1.295 or later if you are counting on the ceiling. In the next capacity incident, the log should show Claude Code waiting, not ending on the repeated 529 error. A job past the ceiling fails on the next capacity error, as intended.

Gotchas

• The watchdog changes how other retry settings behave. CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS (v2.1.292 or later, default 500 milliseconds, maximum 32000) has no effect while the watchdog is set to 1, so use one approach or the other.
• The ceiling is per API request, not per job. A long run with several slow requests can still take longer than one ceiling, which is why we keep the CI timeout.
• Fast mode requests follow their own rate-limit rules, covered on the fast mode page.

Recommended AI prompt

Copy this paragraph into ChatGPT, Claude, Gemini, Grok, or whatever AI you use.