Claude Code 529 Overloaded? Preserve Subagent Work

If a Claude Code subagent stops with API Error: 529 Overloaded, treat it as a temporary server-side failure and the worktree as unfinished. Do not immediately relaunch the same task. First stop new fan-out, preserve the current diff, identify which files the failed agent touched, and run the smallest relevant checks. Resume from the main session only after the service has recovered.

A 529 is not an authentication failure, a billing error, or proof that your repository is corrupt. Anthropic defines 529 overloaded_error as temporary API overload. The dangerous part in a coding workflow is local: a failed subagent can leave edits behind without a final report or tests.

Confirm the Error Boundary

Record the exact failure before changing configuration:

claude --version
git status --short
git diff --stat

Then compare the message with the nearest failure class:

Open Claude Status and note the incident time and affected model. A green status page does not disprove a short-lived or not-yet-posted incident. Recent community reports captured 529 failures before or between status updates.

If the error response includes a request ID, keep it with your private incident notes. Do not paste a session transcript, repository diff, token, or internal path into a public issue.

Stop Fan-Out Before It Multiplies the Damage

Inside Claude Code, open the agent and task views:

/agents
/tasks

Do not start replacement subagents while the service is still returning 529. If other agents are running, stop only work that is duplicated or unsafe. Avoid using a global Ctrl+C as your first response because current Claude Code reports describe one interrupt stopping unrelated background agents.

Expected result: no new agent is editing the same files, and you know whether any other worker is still active.

For future runs, bound subagent fan-out before the task starts. During an outage, fewer writers make the recovery boundary much easier to prove.

Preserve the Current Worktree Without Trusting It

Start with read-only Git inspection:

git status --porcelain=v1
git diff --name-status
git diff --stat
git diff --check

git diff --check can expose conflict markers and whitespace errors, but a clean result does not mean the implementation is complete. It only means that check found no patch-format problem.

Create a recovery folder next to the repository and save separate patches for unstaged and staged tracked changes:

RECOVERY_DIR="../claude-529-recovery-$(date -u +%Y%m%dT%H%M%SZ)"
mkdir -p "$RECOVERY_DIR"

git diff --binary > "$RECOVERY_DIR/unstaged.patch"
git diff --binary --cached > "$RECOVERY_DIR/staged.patch"
git status --short > "$RECOVERY_DIR/status.txt"
git ls-files --others --exclude-standard > "$RECOVERY_DIR/untracked.txt"

ls -lh "$RECOVERY_DIR"

Expected result: the recovery folder contains two patch files plus inventories of changed and untracked paths. An empty staged patch is normal when the agent did not stage anything.

Untracked files are listed but not included in either patch. Review those paths individually before copying them. Do not run git add -A, archive the entire repository, or upload the recovery folder just to make a backup. Untracked files can include local credentials, build output, or large generated assets.

If the repository already had user changes before the agent started, the patch contains both sets of edits. Do not attribute every line to the failed subagent.

Find Where the Subagent Stopped

Compare the original task with the actual diff:

git diff --name-only
git diff --cached --name-only

For each changed file, classify the state as one of these:

• complete and verified;

• plausible but untested;

• partial or internally inconsistent;

• unrelated pre-existing work; or

• unknown ownership.

Look for the failed agent's final visible tool calls in /agents. Claude Code also stores local session records below its configuration directory. You can locate recent subagent transcript files without printing their contents:

CLAUDE_CONFIG_ROOT="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"

find "$CLAUDE_CONFIG_ROOT/projects" \
  -path '*/subagents/agent-*.jsonl' \
  -type f \
  -mmin -180 \
  -print

Treat JSONL as sensitive and its schema as internal. Do not hand-edit it or paste it into an untrusted tool. If the whole conversation is missing, use the Claude Code session-history recovery workflow instead of reconstructing state by guesswork.

Expected result: you can name the last known completed step and the first unverified step. If you cannot, mark the entire agent-owned diff as unverified.

Run the Smallest Relevant Verification

Do not run a full destructive cleanup or broad autofix. Choose checks that match the changed files:

git diff --check

Then run the repository's targeted formatter check, typecheck, or unit test for the smallest affected package. Read the project's contributor instructions before choosing a command.

Expected result: each retained change has a specific passing check, or it remains explicitly unverified. A failed or missing test is a recovery boundary, not a reason to let a fresh agent rewrite everything.

If several editing agents shared one checkout, ownership may be impossible to recover confidently. Preserve the patches, stop all writers, and move future editing tasks into separate Git worktrees.

Wait, Then Resume From the Main Session

Anthropic's API documentation says official SDKs retry transient failures with exponential backoff, but current Claude Code issue reports show failed background subagents can still terminate on a 529. Repeating the prompt during the same incident can therefore create another failed worker without recovering the first one.

Wait until the affected model is stable. Resume the main conversation, not the failed worker, and give it the known boundary:

The previous subagent stopped on API Error 529 Overloaded.
Do not restart the task yet.
Read git status and the current diff only.
List completed-looking changes, unverified changes, and missing tests.
Do not edit files.
Stop after the recovery report

After you review that report, send one bounded continuation task:

Continue only from the first unverified step in the approved recovery report.
Do not redo completed work.
Edit only the listed files.
Run only the named targeted checks.
Return changed files, exact checks, and any remaining unknowns

Expected result: one worker continues the missing portion, and its handoff states exactly what was changed and tested.

Common Recovery Mistakes

Why This Recovery Sequence Works

The API failure and the local repository state are separate systems. Waiting addresses the server-side overload. Patch preservation protects local evidence. A file-by-file audit distinguishes completed work from plausible-looking fragments. One bounded continuation avoids paying another agent to rediscover work or compound partial edits.

This follows the useful structure of How to Expose the Ollama Service API to Your Network: mirror the exact problem wording, answer early, provide reproducible checks, show expected results, separate similar failure classes, and explain why the fix works. The topic is different, but the practical troubleshooting pattern transfers.

Verify One Read-Only Integration After Recovery

Once the repository is stable, verify that the recovered agent can inspect an external incident without copying credentials into its prompt. If the aident command is not installed, tell your coding agent:

Follow https://aident.ai/SETUP.md

Then run:

aident account auth status
aident vault vault --action status
aident capabilities search \
  --query 'read-only GitHub issue search' \
  --targetEnv staging

Inspect the exact Action schema and preflight it before execution. Ask for at most ten recent anthropics/claude-code issues containing 529 or overloaded, with title, date, comments, reactions, status, and URL. Success means one valid preflight and one bounded read-only result set, with no provider credential placed in the prompt.

Ready to test the recovered integration path? Set up Aident Loadout and preflight one read-only Action.

Sources

• Claude API errors, Anthropic documentation, accessed August 4, 2026

• Claude Status, Anthropic service status, accessed August 4, 2026

• Claude Code issue 82520: subagents terminate on API 529, opened July 30, 2026

• Claude Code issue 45248: persistent 529 failures lose subagent work, opened April 8, 2026

• Reddit: Anyone else getting 529 Overloaded?, published July 20, 2026

• Reddit: Model Overloaded, anyone?, published July 26, 2026

• Hacker News: Claude Code getting API Error 529 Overloaded, published July 27, 2026

• YouTube: Claude Code Repeated 529 errors, published July 25, 2026

Review this article when Claude Code adds subagent-level retries or resumability for 529 failures, changes background-agent transcript storage, or documents a supported partial-work handoff.