Aviera
2024
Fix Claude Code API Error: Rate Limit Reached
Fix Claude Code API error: rate limit reached. Tell 429 quota from 529 overload, see when usage resets, then compact, switch models, or buy extra credits.
The needle on the dash still sits above empty, so you merge. Two miles later the engine dies on the shoulder. You tap the glass, then keep arguing with a gauge that was never wired to the tank that actually closed.
Claude Code hits API error: rate limit reached when a request exhausts a rolling 5-hour or weekly quota, or a per-minute ITPM cap from resending large context. Error 529 means the server is overloaded and does not use your quota. Trust claude.ai/settings/usage over /status. Compact the chat, switch models, or run /usage-credits while capacity refills. Weekly usage is a moving timestamp about 168 hours after the first prompt of a new cycle, not a calendar Monday.
You know the before picture. A high-velocity session is humming. The agent is opening files. You send the next prompt and the terminal prints API Error: Rate limit reached.
You run /status. It looks like you still have most of the bar. You wait five minutes. You paste the same error into search. Threads tell you to log out. You do. The wall is still there.
The after picture is slower on purpose. You read the exact string. You open the website ledger. You decide whether this is quota, a per-minute burst, a 529, or a request that was simply too large. You compact, switch models, or buy credits. You stop treating a local percentage as a permission slip.
Commands and strings in this guide come from NotebookLM research dated 15 August 2026 plus the Claude Code error reference, the Claude API rate limits page, the API errors page, and the Help Center article How do usage and length limits work? (cited as July 2026 in the research pack). No live CLI verify on this draft. When a blog disagrees with those pages on HTTP classes, use the docs. When GitHub issue 29579 shows /status at about 16% while the server hard-blocks, treat that mismatch as a known gap, not as a broken install.
This will not work if you delete ~/.claude/credentials.json and expect the weekly window to wipe. That path is real. The wipe is folklore. It will also not work if you stretch a wait on a 529 that needed /model, or if you treat a 413 as a quota.
This page will not cover OAuth 500 during login, a local process exit, which model is “best,” or whether Max is worth the seat. Those jobs live on OAuth timeout 15000ms, Claude Code process exited, How to change the model in Claude Code, and Claude Code Pro pricing. Install and logout depth lives on Install Claude Code.
The Console API (pay-as-you-go tokens, RPM and ITPM headers) is a different product from Pro and Max session quotas. Codex CLI, GitHub Copilot, and Cursor are different products too. Stay on Claude Code unless you are actually on those tools.
The CLI gauge can read low while the server has already closed the gate.
Match the exact error string
You have four envelopes on the kitchen table. One is a closed utility notice. One is a restaurant saying they have no tables. One is a parcel the post office refused because it would not fit the slot. One is a letter that only says “try again.” You do not open the utility notice and then argue with the restaurant. You read the stamp first.
That stamp, here, is the terminal string. The error reference starts with Find your error for a reason. api error: rate limit reached claude code is not the same event as a Claude Code overloaded error, a request too large, or a 500 during OAuth.
HTTP 429 (Too Many Requests) is the family that usually sits under “rate limit reached.” It can mean you burned a rolling 5-hour or weekly usage quota shared across Claude surfaces. It can also mean you spiked ITPM, which is input tokens per minute: how many prompt tokens the API will accept in a short burst. Claude Code is hungry on that dimension because it resends large file trees with almost every turn. The r/ClaudeAI thread is blunt about agent bursts: one exploration of 30-plus files can empty the minute bucket while the 5-hour bucket still looks healthy.
429 and “rate limit reached” are not the same event as 529 or 413.
Match the string first. Then pick the dimension, not a random wait.
529 overloaded
A Claude Code overloaded error is HTTP 529 (overloaded_error). ClaudeLog and the platform errors page treat this as server capacity, not your personal quota. It does not spend your 5-hour bucket.
Wait 2 to 5 minutes, or run /model and leave the saturated family. Capacity is tracked per model. Picker depth and defaults live on How to change the model in Claude Code. Do not rank which model is best here.
Other HTTP strings (short rows, not new jobs)
HTTP 413 (request_too_large) means the raw request body crossed 32 MB before tokenization. Paste less. Point at paths. Compact so images and tool dumps drop out of history.
The 500 family is a retry first. If the 500 landed during login or authorization, that is OAuth timeout 15000ms, not this page. If the CLI died locally with an exit code and no useful HTTP string, that is process exited. Synonyms such as api error 500 claude code, claude code internal server error, and claude code error 500 stay on this URL only as routing. They do not get their own encyclopedia.
HTTP 400 and claude code api error: connection error. showed up as cluster keywords. The research pack does not give a complete CLI recipe. Retry once. Do not invent a connection playbook.
If a log line carries a synthetic tag, treat it as a wrapper or retry layer talking, not necessarily the raw API sentence. Read past the tag to the code underneath.
Why /status can look fine while you are blocked
Imagine you keep a pocket notebook of cash you spent this morning. You wrote three coffees. You feel rich. The bank already declined the card because of a hold you never wrote down. You keep showing the notebook to the cashier.
/status is that notebook. GitHub issue 29579 (freshness note February 2026 in the pack) is the high-signal thread: session-local counters around 10% to 16% while the server already enforces the wall.
Logging out and logging in refreshes credentials. It often does not reset the server-side window. Deleting ~/.claude/credentials.json is the same class of move. Mentioned in user folklore.
Not a quota wipe.
Ground truth is the website ledger at claude.ai/settings/usage. Open it in a browser. Do not screenshot it. Do not argue with the CLI pie until that page agrees.
/status is a local notebook. The website ledger is what blocks you.
That is the part that wastes an afternoon. People debug the install because the local bar looks kind. The install is fine. The ledger is elsewhere.
If you want a live walkthrough of session tokens versus what the server bills, AI Coding Daily’s ccusage demo is the pack video that matches this gap. It does not replace the website.
[EMBED: YouTube - https://www.youtube.com/watch?v=nvBsl7273jA ] Caption: Community walkthrough of session tokens versus what the server bills.
ccusage reads local jsonl
ccusage is a community utility that reads local .jsonl logs (JSON Lines: one JSON object per line) to estimate tokens. Medium confidence in the claim ledger: those logs miss cache writes and prompt-caching the way the server bills. Use it to see a cliff coming. Do not use it as a courtroom exhibit against a 429.
Website ground truth stays at claude.ai/settings/usage.
Some reports name Claude Code v2.1.63 as a version with sticky rate-limit errors. That is medium confidence from bug threads, not an official “this build is broken” notice. If you are on it and the website ledger is already full, upgrading will not invent headroom.
How the 5-hour limit and weekly quota actually work
Think of four buckets on a bench, each with a slow drip from a tap. You can empty the small one in a pour. The large one still has water. You swear the house “has capacity.” You are looking at the wrong bucket.
Platform docs describe a token bucket algorithm: capacity replenishes continuously up to a cap, rather than dumping all at once at midnight. Claude Code approaching 5 hour limit is the rolling session quota talking. There is also a weekly quota. Both are usage limits shared across Claude surfaces. Separate from those are per-minute throughput limits: RPM (requests per minute) and ITPM.
A burst can empty ITPM while the 5-hour bucket still looks half full. Cached tokens can sit differently against ITPM than fresh tokens. That cache-aware ITPM story belongs on Token Caching Best Practices, not as a second limits bible here.
Typical bands, not a promise. Heavy repos often burn out in 2 or 3 turns.
Portkey’s March 2026 synthesis (the pack’s detailed plan table) is the source for typical prompts per 5 hours: Pro about 10 to 40, Max 5x about 50 to 200, Max 20x about 200 to 800. Official language for Pro matches that 10 to 40 band. Users on heavy trees report lockout after 2 or 3 messages, even on Max. Both can be true. The band is typical. A giant context is not typical.
That is why a Pro band of 10 to 40 can sit next to a hard block at message three. The counter you can see cannot stop you; the counter that can is the one you keep refusing to open in a browser.
Full plan comparison and “is Max worth it” stay on Claude Code Pro pricing and the Claude Plan Comparison Guide. No prices on this page.
Per-minute ITPM can empty while the 5-hour bucket still looks healthy.
Console API spend limits and anthropic-ratelimit-* headers apply to API keys and tiers. They are useful vocabulary. They are not your Pro session clock. If you are on a subscription seat, do not paste a Scale-tier RPM table into the argument you are having with /status.
Help Center language also splits usage (how much you can send over time) from length (how deep a single conversation can get). A 413 is length or payload. A 429 on a healthy conversation can still be usage or ITPM.
When does Claude Code usage reset
People want a Monday. Offices run on Mondays. Billing emails run on Mondays. The weekly Claude Code window does not owe you a Monday.
Official pages talk in 7-day language. User threads and a support-bot trail, including the Hacker News item, describe a moving timestamp: about 168 hours after the first prompt of a new cycle. Prefer that moving-timestamp evidence for “when does Claude Code usage reset,” and flag the conflict.
Do not invent a clock.
The 5-hour window rolls. Capacity drips. You do not get a single dump at a wall-clock hour unless you happened to start the window then.
The weekly clock starts at the first prompt of a new cycle, not Monday. Official pages still say 7-day in places.
Resubscribe or upgrade in the middle of a period does not jump the weekly timestamp. You can pay for days you still cannot use. That is an ugly sentence and it is in the sources.
First message and a light warm-up
The 5-hour window starts at the first message of the cycle. A throwaway “hi” at 6am can pin the reset to hours you actually work. Gael Breton’s post is the pack social that says this out loud.
[EMBED: X - https://x.com/GaelBreton/status/1958576661558939992 ] Caption: A morning “hi” can pin the 5-hour window to the workday.
Warm-up as a productized cron is rare. DEV’s Vercel job plus claude setup-token (a long-lived OAuth token whose prefix is sk-ant-oat01-) exists for people who want the window to start before standup. This article is not a cron tutorial. Do not dump OAuth setup. Login hangs belong on OAuth timeout 15000ms.
If you only needed the window to start, a dummy prompt in the real CLI is enough. If you needed a year-long token for automation, that command is the named door.
Keep the token off git.
Spend fewer tokens so the wall arrives later
I tried living on /compact alone for a week. It helped until the agent loaded three MCP servers I never called. MCP is the Model Context Protocol: a way to attach extra tools. Their definitions can ride along every turn. Compact cannot delete a catalog you keep shipping.
Audit first. Then compact. Then switch. Then buy.
Path-scope rules so the agent is not swallowing the whole house style guide on every file.
Disable unused MCP servers. Tool defs can be huge on startup.
/mcp disableis the named move in the research pack.Run
/contextand look at tools versus messages. If tools are the pie, compacting chat will feel like bailing a boat with the tap open.Run
/compactto summarize earlier turns.Start a new chat about every 15 to 20 messages.
Batch questions so you do not pay a full tree walk per curiosity.
Use a cheaper family (Haiku or Sonnet) for cheap turns.
/modelalso leaves a 529-saturated model.Run
/usage-creditson Pro or Max when the quota is actually gone, or when a 1M context window demands credits even though the 5-hour bar looks fine.
Immediate lockout after 2 or 3 prompts is usually giant context or a recursive tool loop, not a mysterious 10-prompt tax. High frequency in GitHub and Reddit. If the agent is exploring 30 files because you asked it to “just look around,” you spent the minute bucket on a tour.
Token caching (cheap cache-reads versus expensive cache-writes) is a list item here. The practice guide is Token Caching Best Practices.
Buy-versus-upgrade economics live on Claude Code Pro pricing. /usage-credits is the in-session door on this page.
A short restore sequence
Use this when the session is blocked and you need a first move, not a philosophy.
Copy the exact terminal string. Match it on the error map above.
Open claude.ai/settings/usage. Treat that page as ground truth.
If the string is 529 or overloaded, wait 2 to 5 minutes or
/model. Do not spend the wait blaming your plan.If the string is 413, stop pasting blobs. Path-ref. Compact attachments.
If the string is rate limit / 429 and the website is full,
/compact, new chat, or/usage-credits. If the website still has headroom, you likely spiked ITPM. Slow the burst. Stop parallel file tours.If you need the window to land on work hours, send the first prompt of a new cycle on purpose. Do not expect Monday.
Confused about which of those is “the” rate limit? Fair. There are several walls. The string plus the website page is how you pick one.
FAQ
When does Claude Code usage reset?
Limits reset on a rolling basis, not a fixed calendar Monday. Five-hour capacity replenishes continuously under the token bucket. Weekly usage, in user and support-bot evidence, is a moving timestamp about 168 hours after the first prompt of a new cycle. Official 7-day wording still exists. Prefer the moving timestamp, and do not treat a resubscribe as a wipe.
Why am I hitting a rate limit even though my usage dashboard shows headroom?
You are often hitting per-minute ITPM, not the 5-hour or weekly quota. Claude Code resends large context (trees, files, tool results) with almost every request. A healthy session bar can sit next to an empty minute bucket.
How many prompts do I actually get per 5-hour window on a Pro plan?
Official-typical language is about 10 to 40 prompts per 5 hours on Pro. Thinking mode and huge windows burn faster. Users on heavy repos report 2 or 3 messages. Treat 10 to 40 as a band, not a coupon.
What is the difference between a 529 overloaded error and a usage limit?
529 is server capacity. It is not your usage limit and does not count against your quota. Wait 2 to 5 minutes or switch models with /model. A usage limit is the 5-hour or weekly bucket, or an ITPM burst that still belongs to you.
Why does /status show a different usage percentage than the website?
/status reads a session-local counter. The website ledger at claude.ai/settings/usage includes server-side factors such as prompt caching that local tools can miss. When they disagree, the website wins.
Can I buy more usage if I hit my limit on a Pro or Max plan?
Yes. Run /usage-credits to buy extra capacity on Pro and Max. That is metered continuation, not a weekly-timestamp jump. Seat-upgrade questions belong on Claude Code Pro pricing.
How can I reduce the tokens Claude Code uses so I do not hit limits as fast?
Disable unused MCP servers, path-scope rules, inspect /context, then /compact. Start fresh every 15 to 20 messages. Batch questions. Use a cheaper model for cheap turns. Compact alone is the move people memorize. It is not the first move if tools own the pie.
Why does the 1M context window model require usage credits?
Extended 1M context is an entitlement check, not proof that your 5-hour bar is empty. Enable metered billing with /usage-credits, or switch to a standard 200K variant with /model. Model catalog depth is How to change the model in Claude Code.
What should I do if I get a 413 request too large error?
The raw body exceeded 32 MB before tokenization. Reference large files by path. Compact so accumulated images and tool dumps leave history. This is size, not quota.
Related internal links
Token Caching Best Practices for ITPM, cache-write versus cache-read
Claude Plan Comparison Guide for Pro versus Max 5x versus Max 20x throughput
Claude Code Pro pricing for buy credits versus upgrade
How to change the model in Claude Code for
/modelpicker and defaultsOAuth timeout 15000ms if the string is login or authorization 500
Claude Code process exited if the CLI died locally
Install Claude Code for credentials path and logout; logout is not a quota reset
Claude Code MCP servers if tool defs are the pie in
/contextClaude Code vs GitHub Copilot and Claude Code vs Gemini CLI if you actually left this product
Maybe a later build will make /status match the ledger. Maybe it will not. The honest uncertainty is the weekly stamp: docs still say 7-day in places, and the moving 168-hour story is what people live. Watch the first prompt of a cycle more closely than the calendar app.
If you only do one thing tonight, open claude.ai/settings/usage, then match the exact error string before you wait, log out, or upgrade. If it is 529, switch models. If the website is empty, compact or buy credits. If the website still has room, stop the file-tour burst. Subscribe if you want the next troubleshooting guide in this series before it hits search.
Until then...
Sage
PS. Tomorrow, before the real task, send a one-word ping at the hour you actually sit down, then write that clock time on a scrap of paper next to the weekly reset line on the website. If the two disagree by more than an evening, you have been planning your week against a Monday that was never in the contract.
Medium SEO settings (paste into Medium Story settings)
Do not publish this block in the article body. Use for Medium SEO Settings + Story preview only. No em-dashes in these fields.
Story title
Story subtitle (preview dek, under 140)
SEO Title (keep primary; Medium suffix under 60 if possible)
SEO Description (154 chars)
Topics (up to 5; only if Medium autocompletes)
Artificial Intelligence
Programming
Software Development
Claude AI (or Claude)
Troubleshooting
Keyword intent covered: primary claude code api error: rate limit reached; secondaries on-page (api error: rate limit reached claude code, claude code overloaded error, claude code approaching 5 hour limit, 500/400/connection as table rows); ranked FAQ when does claude code usage reset plus 8 fillers.
