Taming Claude Code 529 Errors in CI Pipelines

Lachlan Reed

Right, so this one's brought to you by Jellypod AI. A couple of episodes back we skated past CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS, and then the max delay setting got a quick mention too, just tossed out as a closing bullet. Turns out those were pieces of a set. Versions 2.1.295 and 2.1.296, released October 8 and 9, finish it. 2.1.295 added CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS, and 2.1.296 added CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS. Between them you can finally shape how Claude Code behaves when the API throws a 529 overloaded error during an unattended job.

James Turner

And the reason you'd care is the default window is shorter than people think. At your desk, a 529 is no big deal, you wait and hit enter again. In headless mode, a CI runner, or a loop, it kills the process with exit code 1 halfway through. One write up tested this against a mock 529 server. Default backoff starts around 0.55 seconds, then 1.26, 2.05, 4.04, 9.5, 17.7, and levels off around 34 to 38 seconds. Ten retries burn through in 176.2 seconds. Under three minutes. So any capacity crunch longer than that fails your pipeline.

Lachlan Reed

Now, the obvious fix was CLAUDE_CODE_RETRY_WATCHDOG set to 1. That retries 429 and 529 capacity errors indefinitely, backing off up to five minutes between attempts. Problem is, indefinitely means indefinitely. Picture a GitHub Actions job with a 30 minute limit. The watchdog's still patiently waiting when the platform sends a SIGKILL. No error log, no debugging details, nothing salvageable. That's what the new wait cap fixes. It bounds how long the watchdog waits per request, and then the job fails cleanly with an explanatory 529 message, before the runner pulls the plug.

James Turner

Here's the CI pattern. In your job definition, export CLAUDE_CODE_RETRY_WATCHDOG equals 1, then export CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS equals 1,800,000, which is 30 minutes. Then run claude with the p flag, your prompt, say run tests and fix failures, and add the fallback model flag with Sonnet 5.5 and Haiku 5.5. Each model in that chain gets its own retry budget, and since capacity is tracked per model, falling back from an overloaded model often succeeds straight away.

Lachlan Reed

If you'd rather skip the watchdog, there's a tuned backoff pattern. Set CLAUDE_CODE_MAX_RETRIES to 5. Default is 10, and it's capped at 15 unless the watchdog is on. Then set the base delay to 4,000 milliseconds and the new max delay to 60,000. Base delay has a range of 500 to 32,000, with a 500 default, and it arrived in 2.1.292. The point is a small retry budget now stretches across several minutes, instead of getting blown through in seconds.

James Turner

A few gotchas. First, the wait cap is per request, not per job. A session with many turns can burn several wait periods, so leave headroom under your runner timeout. Second, retries only happen for requests that failed before Claude produced any completed text or ran any tool calls. If a stream dies after tools have run, Claude Code won't replay them, which protects you from duplicate writes or a repeated destructive shell command. Third, a 429 from a hard spend cap, exhausted credits, or an org policy denial comes back with a header telling it not to retry, so it fails immediately. And please don't put the watchdog in your .bashrc or .zshrc. Your interactive sessions will look frozen. Scope it to CI containers and automated jobs.

Lachlan Reed

Quick quality of life round. In 2.1.296, Edit and NotebookEdit now refuse to edit files that aren't valid UTF 8, like Shift JIS, Windows 1252, or GBK, where before they quietly mangled every non ASCII character. Turns or bang commands started while a session moves to the background with the left arrow are now stopped, not run out of sight. On Windows, PowerShell commands over 1 KB used to always prompt, and allow rules and read only detection now apply up to 32 KB.

James Turner

Two more. Run claude with debug, and command hooks now log their command, plugin, outcome, and duration when they finish, so a slow hook is easy to spot. And CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL runs every workflow agent on one model, say Haiku 5.5, while your regular subagents keep their own. If a nightly job's been dying on a 529, set the wait cap and a fallback chain this week.