Claude Code 529 errors and rate limits: how to tell which one you're hitting

You’re mid-session, the agent’s making real progress, and then it stops with something like Error: 529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}. Or you get a message telling you you’ve hit a usage limit and to try again later. Both look like “Claude Code is broken.” Neither one is — but they’re two different problems with two different fixes, and mixing them up is why people burn time reinstalling the CLI or regenerating API keys when that does nothing.

If you searched “claude code 529 error,” “claude code rate limit,” or “is claude code down,” this covers both.

First: figure out which one you’re actually looking at

These get lumped together because they both interrupt a session, but they come from different places.

529 “overloaded” is Anthropic’s servers, not you. It means Anthropic’s infrastructure is at capacity right now — this happens during peak US daytime hours especially. It’s a standard HTTP 529 response, the same family of error you’d see from any API under heavy load. It has nothing to do with your account, your usage history, or how much you’ve used Claude Code today. It can happen on a session you just started.

A rate limit message is about your usage, not server load. This is Anthropic (or your plan) telling you that you’ve used up your allotted throughput for the current window. It shows up after sustained heavy use — long agent sessions, large contexts, a lot of back-to-back tool calls — not out of nowhere on a fresh session.

The fastest way to tell them apart:

1. Read the actual error text. “Overloaded” / “529” = capacity. “Rate limit” / “usage limit” = your quota.
2. Check how long you’d been working. If this is the first message of a new session, it’s almost certainly a 529 — you haven’t used anything yet. If you’ve been running a long agentic task for 30+ minutes with a big context, it’s more likely a rate limit.
3. Try again in 60–90 seconds without changing anything else. A 529 typically clears on its own within a short window because it’s about momentary load, not your account state. If the exact same request succeeds a minute later with zero changes on your end, that confirms it was a capacity error, not a limit.
4. If retrying immediately gives you the same error repeatedly over several minutes, and especially if it names a specific limit or reset time, that’s the rate limit case, not a transient overload.

What actually helps with a 529

1. Just retry. Claude Code’s CLI already does automatic retries with backoff for overloaded errors in most cases — if you’re scripting around the CLI or hitting the API directly, implement the same (short delay, retry, longer delay, retry).
2. Shift heavy sessions off peak US hours if you can. Overload errors cluster around the busiest hours for Anthropic’s infrastructure. Early morning or late evening (US time) sessions hit this less.
3. Break work into smaller requests. A single enormous tool-call-heavy turn is more likely to get caught mid-flight by a capacity blip than several smaller ones — not because smaller requests are exempt from 529s, but because you have more natural checkpoints to resume from if one does hit.
4. Save your work state before long unattended runs. If you’re kicking off a long autonomous agent task, make sure whatever it’s building is being committed/saved incrementally, so a 529 mid-session costs you a retry, not lost work.

None of this is a sign your setup is wrong. It’s the AI equivalent of a “server busy” message from any high-traffic API — the fix is patience and retry logic, not configuration changes.

What actually helps with a rate limit

1. Know which window you’re in. Rate limits on subscription plans reset on a rolling basis, not at midnight — so “I’ll just wait until tomorrow” isn’t the right mental model. Waiting a shorter, specific amount of time is usually enough for the window to roll forward.
2. Run /compact before long sessions get long. A big part of what eats through usage fast is context size — every turn in a long conversation re-sends accumulated context. Compacting periodically keeps each turn cheaper, which stretches your usage window further.
3. Split long agent sessions into focused chunks instead of one marathon session. Instead of one continuous session doing feature build → debug → refactor → docs, close out and start fresh between distinct tasks. Fresh sessions start with a smaller context footprint, which uses your limit more slowly per unit of actual work done.
4. Watch for sessions with heavy tool-call loops. Agentic loops that repeatedly read large files, run broad searches, or retry failed edits burn through usage fast without necessarily producing proportional progress. If a session is spinning, it’s often cheaper to stop, compact, and restate the task precisely than to let it keep grinding.
5. If you’re consistently hitting limits on a normal workload, that’s a signal about tier, not a bug. Heavier usage tiers exist precisely for people running longer or more frequent agent sessions than a standard plan is sized for. If you’re hitting limits most days doing normal work (not a single unusual binge session), that’s the actual fix — not a workaround.

What doesn’t help — and wastes your time

• Reinstalling or updating the Claude Code CLI. Neither error is a client bug. A fresh install will hit the exact same 529 or rate limit, because the cause is server-side or account-side, not local.
• Regenerating or swapping API keys, if you’re on a subscription plan. Rate limits and overload errors on subscription usage aren’t tied to a specific key — cycling keys doesn’t reset a usage window or route around server load.
• Restarting your machine, clearing caches, or reinstalling dependencies. These fix local environment issues. This isn’t one.
• Assuming a 529 means you’ve been rate limited and going quiet for hours. You’ll needlessly stall work that would have resumed in under a minute with a simple retry.

How to verify you’re actually past it

1. For a 529: resend the exact same request. If it succeeds with no changes on your end, the overload has cleared — you’re good to keep going.
2. For a rate limit: check whether the specific error message or CLI output gives you a reset time or window; if not, wait a conservative interval (a few minutes for light overages, longer for sustained heavy use) and retry with a smaller request first — not immediately picking back up a huge agentic task — to confirm the window has rolled over before committing to a long session again.
3. Either way, confirm normal behavior with a trivial request first (a short question, not a multi-file agent task) before resuming the heavy session you were in. That isolates whether you’re actually clear, versus about to hit the same wall two turns into a big task.