Claude Code 429 Error: What It Means and How to Fix It

You ask Claude Code to make one small change and get a 429 error instead. Opening another terminal does not help. Before changing your subscription or replacing your API key, identify who refused the request and why. This guide gives you a short recovery path, then explains how to stop the same failure interrupting your next session.

First, save the clue that disappears when you retry

Copy the complete error message, the time and timezone, and any request ID. Keep credentials out of that note. A screenshot of the number 429 alone leaves out the information that distinguishes a temporary traffic restriction from a spending cap. If you are working through an employer's gateway, note that gateway's hostname too.

Then stop repeatedly submitting the same task. One deliberate retry after the indicated waiting period is useful evidence. Ten concurrent sessions are not: they add traffic and make it harder to tell whether the original problem has cleared. Leave your repository as it is until you have checked whether the agent already changed files.

git status --short
git diff --stat

Find out which service your terminal is using

Claude Code is the client you interact with. The service receiving its model requests may be Anthropic or a separate gateway. The identity and billing rules of that service determine what the error means. A subscription shown in one dashboard does not establish the allowance of a different API account.

Start with the endpoint configured for this terminal. In Bash, the command below prints only the endpoint, not your API key. A blank custom endpoint is a clue, not a complete authentication diagnosis; application settings and your sign-in state can still matter. If a team manages your configuration, ask which dashboard represents the route you are using.

printf 'Custom endpoint: %s\n' "${ANTHROPIC_BASE_URL:-not set in this shell}"

Use the message to choose the recovery path

Anthropic documents 429 responses for rate limits and certain spending caps. A temporary throttle and an exhausted budget therefore need different actions. Read the error body alongside the account's usage information; do not infer the reset time from the status code alone. The official API error reference describes those distinctions.

For temporary throttling, a Retry-After response header, when present, supplies a waiting interval. Respect it. For a stated spending cap, waiting a few seconds is unlikely to change the result: inspect the account's budget and access state. If a third-party gateway returned the error, consult its own error explanation rather than assuming Anthropic's fields pass through unchanged.

• A message about request or token throughput: reduce parallel work and wait for the indicated recovery interval.
• A message about a budget or spending cap: inspect the relevant workspace or account's spending controls.
• An unclear gateway error: collect its request ID and ask that gateway's support team which limit was reached.

Why a short prompt can still hit a limit

The words you just typed are only part of an agent request. Its conversation may also contain previous replies, file excerpts, tool definitions and command results. Asking 'continue' after a long investigation can send substantially more context than a new conversation with a precise question.

Imagine two workflows. In the first, the agent receives an entire build log, scans a repository and tries several fixes in parallel. In the second, you give it the failing test, the relevant source file and the expected outcome. Both may begin with a short instruction, but they create different workloads. Restrict the investigation to evidence that helps solve the problem rather than repeatedly supplying everything.

Before starting a shorter session, record the current goal, changed files, last verified result and unresolved question. This handoff preserves useful work. Do not delete the repository or reset changes merely because a remote model request was refused.

Recover one session before restarting everything

After the waiting interval or account correction, send a small request from one session. If it works, resume one bounded task. Only restore parallel workers after you have observed stable behavior. This makes your recovery test interpretable: you know which change preceded success.

If the small request still fails, keep the new error and compare it with the original. A different error may mean you fixed the first problem and uncovered another. If both fail identically, report that result together with the route and timestamps. Avoid publishing complete logs without checking them for source code, personal data and credentials.

If you are building a client, give retries an owner

Retry logic needs one clear owner. An SDK, a gateway and your application can each retry the same failure, multiplying attempts. Inspect existing behavior before adding another loop. Use a bounded number of attempts, a total deadline and a delay policy that honors the server's instructions.

Keep model-request retries separate from tool execution. A refused model request does not establish that a preceding command, deployment or write failed. Record completed tool actions and inspect their results before replaying a whole agent turn. This distinction matters most when an action changes an external system.

Measure whether the change helped by recording failures per completed task, peak parallel sessions and time lost waiting. A successful single request is a starting point; the more useful result is completing your normal workflow without repeating the same interruption.

Would changing providers solve it?

A different route can have different quotas and capacity, but switching is not a universal fix. First identify whether your bottleneck is budget, throughput or an application retry loop. Moving the loop unchanged may recreate the problem elsewhere.

Kintio publishes this guide and offers an alternative API route. If you evaluate it, test your actual coding task, required model behavior and tool calls, and read the current plan conditions. Treat compatibility, quality and capacity as separate questions. There is no technical reason to assume the word 'unlimited' removes every practical constraint.

Frequently asked questions

Should I generate a new API key?

Not as the first response to a 429. Determine the limiting account or workspace first. Replacing a key usually does not change the quota attached to that account.

Can I retry immediately?

Follow the server's waiting guidance when available. Repeated immediate retries add load and can delay useful work. Spending-cap errors require an account or budget correction rather than a rapid retry loop.

Will I lose my edits?

A failed model request does not automatically remove local changes. Inspect git status and your diff before restarting a session, and preserve uncommitted work.

Related guides

• Connect Claude Code to a custom API endpoint
• What Anthropic-compatible means

Last updated: 2026-10-02