Claude API Error Codes: 400, 401, 429, 529 and How to Fix

Short answer

The Claude API reports every failure as JSON with an HTTP status and an error.type: 400 invalid_request_error (something is wrong in the request body), 401 authentication_error (missing or wrong key), 403 permission_error, 404 not_found_error (wrong path or model ID), 413 request_too_large, 429 rate_limit_error, 500 api_error and 529 overloaded_error. Fix 4xx errors by changing the request, because sending it again unchanged fails again; retry 429, 500, 503 and 529 with exponential backoff and honor the retry-after header when it is present. On APIVAI the same codes apply, plus 402 insufficient_quota when a key's budget is used up, and the default limit is 60 requests per minute per key. Most 404s come from the base URL: use https://api.apivai.com for the Anthropic format and https://api.apivai.com/v1 for the OpenAI format.

What does a Claude API error response look like?

Anthropic's API returns errors as JSON with a top-level error object that always has a type and a message, as described on the official Claude API errors page. APIVAI answers in the same shape:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Not found. Check the model name and the endpoint path."
  }
}

The OpenAI format (POST /v1/chat/completions and /v1/responses) traditionally uses {"error": {"message": "...", "type": "...", "param": null, "code": "..."}}. On APIVAI, errors on these endpoints use the same body as above. OpenAI SDKs and tools read error.message and error.type, which are always there; for 400, 404 and 413 errors the body can also carry code and param when they explain which field failed.

Always read error.message first. For request problems (400, 404, 413) it usually names the exact field or model that caused the error.

What do the Claude API error codes mean?

HTTP	error.type	What it means	What to do	Retry?
400	`invalid_request_error`	Bad body or parameters	Fix the field named in the message	No
401	`authentication_error`	Key missing or not valid	Check the key and the header	No
402	`insufficient_quota`	The key's budget is used up (APIVAI)	Add budget to the key in the Dashboard	No
403	`permission_error`	Account disabled or resource not allowed	Contact support	No
404	`not_found_error`	Wrong path, base URL or model ID	Check `/v1` and the model ID	No
413	`request_too_large`	Request body too big	Send less data	No
429	`rate_limit_error`	Too many requests per minute, or key budget used up	Back off; read the message	Yes, with backoff
500	`api_error`	Unexpected server error	Retry with backoff	Yes
503 / 529	`overloaded_error`	Temporarily overloaded	Retry with backoff	Yes

Anthropic's official list also contains 402 billing_error (a payment problem on an Anthropic account), 409 conflict_error and 504 timeout_error. For long generations, the official advice against timeouts is to use streaming. On APIVAI, 402 always means the budget of the key you are using is used up.

Why do I get 401 "invalid x-api-key" or "Invalid API key"?

A 401 authentication_error means the request reached the API but the key was not accepted. APIVAI returns "Missing API key." when no key was sent at all and "Invalid API key." when the key is not one of yours.

Check these in order:

The header. The Anthropic format normally sends x-api-key: <key> and the OpenAI format sends Authorization: Bearer <key>. APIVAI accepts either header on both formats, so a 401 here is about the key itself, not about which header you used.
The key text. Copy it again from the Dashboard; a missing character, a space or quotes pasted into the field are common.
A different key is being sent. An old ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable can win over the key you typed in a tool's settings. The Claude Code setup guide explains which variables Claude Code reads.
The key was deleted or regenerated. A regenerated key replaces the old one; update every tool that used it.

A 403 permission_error with "This account is disabled. Contact support." means the key is valid but the account behind it is disabled; changing the key will not help, so write to support.

How do I fix 429 rate_limit_error and 402 insufficient_quota?

On APIVAI, each key has two limits:

A request rate. The default is 60 requests per minute per key. Agents that fire many calls in parallel can exceed it. Lower the concurrency, retry with backoff, or ask support to raise the limit.
A budget. Every key has its own budget, taken from your account balance when you create the key or add budget to it. When the budget is used up, requests fail with 402 insufficient_quota ("This key has no budget left. Add budget to the key in the dashboard."), or with a 429 whose message says the key budget is used up.

Budget errors do not go away by retrying. Open the Dashboard and add budget to that key. If your account balance is empty as well, top up first (from $10). Your balance can have money while a single key has none: the key's own budget is what counts for its requests. Current per-token prices are on the pricing page.

What is overloaded_error (529), and how should I retry?

overloaded_error means the service is temporarily overloaded. It is not caused by your request, and the same request usually succeeds a little later. APIVAI returns it as 529, or as 503 with the same overloaded_error type. 500 api_error is handled the same way.

The right pattern is exponential backoff: wait about 1 s, then 2 s, 4 s, 8 s, add a little random jitter, and stop after a few attempts. If the response has a retry-after header, wait at least that long; APIVAI passes retry-after and retry-after-ms through when they are set.

The official Anthropic SDKs already do this: they retry connection errors, 429 and 5xx responses twice by default with exponential backoff and honor retry-after. You only raise max_retries:

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.apivai.com",
    api_key="YOUR_APIVAI_KEY",
    max_retries=5,  # default is 2
)

try:
    msg = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=4096,
        messages=[{"role": "user", "content": "Hello"}],
    )
    print("".join(b.text for b in msg.content if b.type == "text"))
except anthropic.APIStatusError as e:
    print(e.status_code, e.response.headers.get("request-id"), e.message)

Without an SDK, a small loop is enough. It retries only the temporary codes and stops when a 429 is about the budget:

import random, time, requests

RETRY = {429, 500, 503, 529}

def post_with_backoff(url, headers, body, attempts=5):
    for i in range(attempts):
        r = requests.post(url, headers=headers, json=body, timeout=600)
        if r.status_code not in RETRY or "budget" in r.text:
            return r
        wait = float(r.headers.get("retry-after", 2 ** i))
        time.sleep(wait + random.random())
    return r

Why do I get 404 not_found_error?

Almost always it is the base URL or the model ID:

Anthropic format: base URL https://api.apivai.com with no /v1. The Anthropic SDK and Claude Code add /v1/messages themselves, so https://api.apivai.com/v1 becomes /v1/v1/messages and fails.
OpenAI format: base URL https://api.apivai.com/v1, exactly one /v1. Without it, the request goes to /chat/completions and APIVAI answers "Unknown endpoint".
Wrong host: requests sent to apivai.com instead of api.apivai.com get a 404 whose message says "Wrong base URL" and lists both correct addresses.
Model ID: use an exact ID such as claude-sonnet-4-6, not a display name. List the IDs your key can use:

curl https://api.apivai.com/v1/models \
  -H "Authorization: Bearer YOUR_APIVAI_KEY"

Claude models work in both formats; GPT models such as gpt-5.5 only in the OpenAI format. More on each format: Claude API proxy and OpenAI-compatible API.

Why does a 400 invalid_request_error happen?

A 400 means the API understood the request but refused its content. The message names the problem. Frequent ones:

max_tokens missing in an Anthropic-format request (it is required there).
The conversation ends with an assistant message (prefill). Claude 4.6 and later models reject it; end with a user message.
An old thinking setting: newer models such as claude-opus-5-5 reject thinking: {"type": "enabled"} and expect adaptive thinking instead. Remove the thinking field to use the default.
Thinking blocks edited or dropped before being sent back in a tool-use loop. Pass them back exactly as received.

A related problem is not an error at all: empty or cut-off replies. Thinking is on by default and its tokens count as output, so a small max_tokens can be spent before any text appears. The response ends with stop_reason: "max_tokens" (or finish_reason: "length" in the OpenAI format). Raise max_tokens to 4096 or more.

413 request_too_large means the body itself is too big. Anthropic's limit for the Messages API is 32 MB. Large base64 files and very long histories are the usual cause: send fewer or smaller files, or trim old turns.

How do errors show up in a streaming response?

With "stream": true, the HTTP status is 200 as soon as the stream starts, so a later failure cannot change it. Instead it arrives as an event inside the stream. Anthropic's streaming docs give this example:

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

If a stream through APIVAI stops before it is complete, APIVAI sends an event: error with api_error and "The response was interrupted. Please retry." instead of ending silently, so the SDKs raise an exception rather than return half an answer. Treat it like a 500: retry the whole request.

How do I find the request ID?

Responses can carry a request-id header (some services use x-request-id); APIVAI passes it through whenever it is present. Print the headers with curl:

curl -sS -D - https://api.apivai.com/v1/messages \
  -H "x-api-key: YOUR_APIVAI_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-4-6", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hi"}]}'

In the Python SDK, a successful response has msg._request_id, and an exception has e.response.headers. Include the ID, the time and the error message when you contact support.

What are the most common causes, at a glance?

Symptom	Likely cause	Fix
404 on every request	`/v1` missing, extra or doubled	Anthropic: `https://api.apivai.com`; OpenAI: `https://api.apivai.com/v1`
401 with a key that looks right	An old environment variable sends another key	Unset it or replace it with the APIVAI key
404 or 400 naming the model	Typo or display name	Copy the ID from `GET /v1/models`
Empty or cut-off replies	`max_tokens` too small with thinking	4096 or more
413	Large files in the body	Send less data
429 during agent runs	More than 60 requests per minute	Lower concurrency, back off
402, or 429 about budget	Key budget used up	Add budget to the key
529 / 503	Temporary overload	Retry with backoff

Tool-specific setups are in the docs and in guides such as Cline with Claude and GPT.

FAQ

Should I retry a 400 or 401 error?

No. 4xx errors other than 429 describe a problem in the request or the key, and the same request fails the same way. Fix the cause first.

What is the difference between 429 and 529?

429 is about your own limits: requests per minute, or on APIVAI also the key's budget. 529 overloaded_error is a temporary overload that does not depend on your usage; both 429 rate limits and 529 are retried with backoff.

Does the Anthropic SDK retry automatically?

Yes. It retries connection errors, 429 and 5xx responses twice by default with exponential backoff and respects retry-after. Set max_retries on the client to change it, or to 0 to turn it off.

Why does my reply come back empty with no error?

Thinking used the whole max_tokens before the visible text. Raise max_tokens to 4096 or more; thinking tokens are billed as output tokens.

My account has balance, so why do I get 402?

The balance and the key's budget are separate. Each key spends only its own budget; add budget to that key in the Dashboard.

Create an account, top up from $10 and create a key to call Claude and GPT with one API.