Claude API errors explained: server error 500, overloaded 529, rate limit 429, bad request 400 — and the fix for each

Every developer using the Claude API encounters errors eventually. Some are your fault (malformed requests), some are Anthropic's (server issues), and some are architectural (rate limits during heavy use). This guide covers every common Claude API error code with real causes, concrete fixes, and production-ready retry logic. It also explains how routing through a gateway with multiple upstream accounts can reduce the frequency of rate-limit and overload errors.

Check access and the model before retrying

Confirm your plan or balance access is active, check the key group, and use a model returned for that key. A successful model-list response is a starting check; verify one small generation request before a larger agent run.

Use models and key groups and the agent setup checklist to separate access problems from tool configuration and upstream errors.

"Claude server error": which one do you actually have?

"Claude server error" is what people type when the API stops answering, but the number in the message decides what to do. A **500** is the API failing internally — wait, retry, or switch model. A **529** is the model being saturated for everyone — same treatment, and it clears on its own. A **429** is a limit you hit — slow down or reduce parallel requests.

A **400** means the request itself was rejected — retrying the same thing will fail again. Find your code below; each section gives the exact message, the cause and the fix. If you are seeing the error inside Claude Code rather than in your own code, the Claude Code error guides at /claude-code/errors/ cover the CLI-specific messages (OAuth timeouts, "process exited with code 1", tool-use concurrency).

Error 400 — Bad Request

A 400 error means your request is structurally invalid. The Claude API rejected it before even attempting to generate a response. The error body contains a message explaining what is wrong — always read it carefully. Common causes include: messages array is empty or malformed, content field is null instead of a string, max_tokens exceeds the model's limit, model identifier does not exist, system prompt is in the wrong format, or tool definitions have schema errors.

The most frequent 400 error for Claude Code users is context length exceeded. When your conversation history grows beyond the model's context window (200K tokens for most Claude models), the API returns a 400 with a message about input being too long. The fix is to use /compact to summarize history, remove large file contents from context, or start a new session. This is not a rate limit — it is a hard constraint on request size.

Another common 400 is sending an unsupported parameter or model version. If you recently upgraded your SDK or changed model identifiers, double-check that every field in your request matches the current API specification. Model IDs are case-sensitive and version-specific — 'claude-opus-4-6' is valid but 'Claude-Opus-4.6' is not. When in doubt, query the /v1/models endpoint to see exactly what identifiers the provider accepts.

Error 400 - "Input Is Too Long for Requested Model"

This specific 400 error means your request (system prompt + messages + any tool definitions) exceeds the model’s context window. It is not a rate limit and retrying will not fix it - the same payload will fail every time until you reduce the input or move to a larger-context model.

Three practical fixes, in order of effort: first, trim the conversation history you are resending - most chat apps only need the last few turns plus a running summary, not the full transcript. Second, count tokens before sending (the token-counting endpoint is free) and enforce a hard input budget in your code. Third, if you genuinely need the full context - whole repositories, book-length documents - switch to a 1M-context model such as Fable 5, where the same request fits comfortably.

A common gotcha in agentic tools: long-running sessions accumulate tool results and file contents until one more turn tips the request over the limit. If the error appears mid-session in Claude Code or a similar agent, compact or clear the session context rather than shrinking your prompt.

Error 429 — "Rate Limit Reached" / "Rate Exceeded"

The same condition shows up under two wordings. The API returns HTTP 429 with rate_limit_error; claude.ai and Claude Code display it as "rate exceeded" or "rate limit reached". Whichever text you see, the cause is identical: your account has used its allowance for the current window and requests are being refused until it resets.

A 429 means you have exceeded the allowed request rate. The response includes a Retry-After header telling you how many seconds to wait before retrying. Anthropic's rate limits operate on multiple dimensions: requests per minute (RPM), tokens per minute (TPM), and tokens per day (TPD). Hitting any one of these triggers a 429. The error message usually indicates which limit was reached.

For Claude Code users, rate limits are the most frustrating error because they interrupt workflow. A single developer running Claude Code with subagents can easily hit RPM limits during parallel operations, or TPM limits during sessions with large files in context. The limits vary by account tier — lower tiers have stricter limits that heavy agentic usage routinely exceeds.

The correct response to a 429 is exponential backoff with jitter. Wait the Retry-After duration, then add randomized delay to avoid thundering herd if multiple clients hit the limit simultaneously. A gateway like AI Prime Tech Unlimited helps reduce 429 errors by routing requests across multiple upstream accounts, effectively multiplying the available rate-limit budget. When one upstream account is rate-limited, the gateway routes to another.

Error 500 — Internal Server Error

A 500 error means something went wrong on the server side — not your fault, not something you can fix by changing your request. These are transient: the same request that failed with a 500 will likely succeed if you retry it after a short delay. Anthropic's infrastructure occasionally returns 500s during deployments, capacity changes, or internal service disruptions.

The correct handling for 500 errors is simple retry with backoff. Wait 1-2 seconds and retry the exact same request. If it fails again, wait 4 seconds, then 8, up to a maximum of about 60 seconds. Most 500 errors resolve within the first retry. If you get sustained 500s for more than a few minutes, check Anthropic's status page or the gateway's status endpoint for known incidents.

Do not modify your request in response to a 500 — the issue is server-side. Changing your prompt, reducing context, or switching models will not help and wastes development time debugging a problem that is not yours. The only action items are: retry, wait longer if retries fail, and alert if it persists beyond a reasonable window (5-10 minutes of continuous failures).

Error 529 — "Claude Server Is Overloaded" (overloaded_error)

The 529 status code is Anthropic-specific and means the API is experiencing high demand — the model you requested is temporarily at capacity. Unlike a 429 (which means YOUR rate limit is exceeded), a 529 means the SYSTEM is overloaded regardless of your individual limits. You have not done anything wrong; there is simply more demand than available compute at that moment.

529 errors are most common during peak hours (US business hours), immediately after new model releases (everyone tests the new model simultaneously), and during viral moments when usage spikes across all customers. They are less common for Sonnet and Haiku than for Opus, because Opus requires more compute per request and has tighter capacity constraints.

Handle 529s with longer backoff than 500s. Start with a 5-10 second wait and increase exponentially. If you are building production systems, consider model fallback: when Opus returns 529, fall back to Sonnet for that request. A gateway with multiple upstream accounts can also help — the overload may affect some accounts' priority tiers differently than others, giving the gateway more routing options during peak demand.

"No Healthy Upstream" — Not a Claude Error, an Infrastructure One

"No healthy upstream" is not returned by the Claude API itself. It is the message a load balancer or ingress proxy (typically Envoy) emits when every backend instance behind it is unavailable. You will see it on claude.ai during an outage, and from any proxy or gateway whose pool of upstream connections is exhausted or failing health checks.

There is nothing to fix in your code. Treat it as transient: check status.anthropic.com, wait, and retry with exponential backoff exactly as you would for a 529. If it persists for more than a few minutes on the official endpoint, it is an outage; if it comes from a third-party gateway, that gateway has lost all of its upstream capacity.

This is one of the failure modes a multi-account gateway is built to absorb: when one upstream account is throttled or unhealthy, the request is routed to another rather than surfacing the error to you.

Production-Ready Retry Logic

Good retry logic handles all transient errors (429, 500, 529) uniformly with exponential backoff and jitter, while treating permanent errors (400, 401, 403) as non-retryable. The pattern is: attempt the request, check the status code, if retryable wait with backoff and retry up to N times, if not retryable raise immediately. Maximum retry count should be 3-5 for most applications.

Jitter prevents synchronized retries. If ten clients all hit a rate limit at the same time and all retry after exactly 2 seconds, they will all fail again simultaneously. Adding random jitter (multiply the delay by a random factor between 0.5 and 1.5) spreads retries across time and dramatically improves success rates. Every production Claude API client should include jitter.

For Claude Code and agentic workflows, implement retry at the HTTP client level so individual tool calls and subagent requests benefit automatically. The Anthropic SDK already includes basic retry logic, but you may want to customize timeouts and max retries for your use case. If you use AI Prime Tech Unlimited, the gateway handles upstream retries and routing internally, reducing the errors your client sees in the first place.

How a Gateway Reduces These Errors

A well-architected gateway like AI Prime Tech Unlimited reduces error frequency in several ways. For rate limits (429), the gateway distributes requests across multiple upstream API accounts, so your effective rate limit is the sum of all upstream accounts rather than a single account's allocation. For overload errors (529), the gateway can retry on different upstream accounts that may have different priority levels or queue positions.

For server errors (500), the gateway can retry transparently before returning the error to your client — you see a slightly slower response instead of an error. For 400 errors, the gateway cannot help because the request itself is invalid, but good gateways provide clearer error messages that help you debug faster than raw Anthropic error responses.

The net effect for developers is fewer errors reaching your application, less retry logic needed on the client side, and more stable performance during peak hours. This is especially valuable for Claude Code sessions where an error mid-task can disrupt flow, and for production applications where error rates directly impact user experience. The unlimited plan's flat rate means these retries and reroutings cost you nothing extra.

import anthropic
import time
import random

client = anthropic.Anthropic(
    api_key="YOUR_KEY",
    base_url="https://aiprimetech.io",
)

def call_with_retry(messages, model="claude-sonnet-4-5", max_retries=4):
    for attempt in range(max_retries + 1):
        try:
            return client.messages.create(
                model=model,
                max_tokens=4096,
                messages=messages,
            )
        except anthropic.RateLimitError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            print(f"Rate limited, waiting {wait:.1f}s...")
            time.sleep(wait)
        except anthropic.InternalServerError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            time.sleep(wait)
        except anthropic.BadRequestError:
            raise  # Don't retry 400s

# Usage:
resp = call_with_retry([{"role": "user", "content": "Hello"}])

Frequently asked questions

AI Prime Tech is an independent API gateway. It is not affiliated with, endorsed by, or a reseller of Anthropic. Claude and related model names are trademarks of their respective owners.