Claude Code
Claude Code rate limit vs usage limit: which one you hit
"Rate limit" covers two different limits in Claude Code. On a Pro or Max subscription you are hitting the plan usage limit: a five-hour session limit or a weekly limit, which lasts until the window resets. With an API key you are hitting the API rate limits on requests and tokens, which return an HTTP 429 error and usually clear within moments. Which one it is decides what to do.
Plan usage limit (subscriptions)
Shared across claude.ai, Claude Code and Claude Desktop, with a session limit that resets every five hours and weekly limits that reset once a week. Hitting it stops Claude Code until the window resets, and the message says when. Details: Claude Code usage limit and when it resets.
API rate limit (API keys)
Anthropic's API caps requests and tokens per minute by usage tier, as described in its rate limits documentation. Exceeding a cap returns a 429 error, and the response tells the client how long to wait before retrying. This is separate from the plan windows; see usage vs API usage.
How to tell which one you hit
- Signed in with a Claude subscription? It is the plan usage limit. The message mentions a reset time, and
/usageshows the figures. - Using an API key or a cloud provider? It is an API rate limit (or an overloaded-service error, which is not about you at all). Claude Code retries, and slowing down or lowering the number of parallel sessions helps.
- Not sure? If a five-hour or weekly percentage is at 100%, it is the plan. The free Usage Meter shows both in the VS Code status bar so you can see it before it happens.
Parallel sessions make both worse
Every session you add draws on the same plan allowance, and on an API key the same per-minute caps. Four agents working at once reach either limit sooner than one. How parallel sessions use the limits covers what to watch; Paneherd shows the plan figures and each pane's approximate share in the VS Code sidebar.
Frequently asked questions
Why am I rate limited when I barely used Claude Code?
Usually other tools drew on the same allowance, or one long session spent more than it seems. See why am I rate limited.
Does waiting fix it?
Yes for both. A plan limit lasts until its window resets; an API rate limit usually clears within moments.