Claude Code errors fall into two main categories, and most search results cover only one of them. Client errors during installation and execution, and API errors returned when calling a model, have completely different causes and fixes. This article focuses on the second category — 401, 429, and 529 — because these are the first errors you encounter when switching from a subscription to an API key.
Error strings appear in English everywhere. Below, the strings are left as they are, with the explanations in English.
First, narrow down the cause in 30 seconds
Before changing settings, send one request directly to the endpoint. This single request distinguishes between a client issue, an authentication issue, and a server issue.
# 오류가 클라이언트 문제인지 엔드포인트 문제인지 30초 만에 가르는 방법.
# 200이 돌아오면 키와 주소는 정상이고, 남은 문제는 Claude Code 설정입니다.
curl -sS https://api.kunavo.com/v1/messages \
-H "Authorization: Bearer sk-kn-..." \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-haiku-4-5","max_tokens":16,
"messages":[{"role":"user","content":"ping"}]}'| Result | Meaning |
|---|---|
| 200 | The key and address are working — the remaining issue is Claude Code configuration |
401 | Authentication — usually the wrong header type |
429 | Rate limit — determine whether it’s a subscription limit or API limit |
529 overloaded_error | Upstream overload — not a problem on your end |
401 — the header is wrong, not the key
If you keep getting 401s after issuing new keys several times, look at how you’re sending it, not the value. Claude Code sends ANTHROPIC_AUTH_TOKEN in the Authorization: Bearer header, and ANTHROPIC_API_KEY in the x-api-key header. Most gateways expect the former, so swapping the two variables results in a 401 even with a valid key.
It’s also common for both variables to be set at once. Remove one, open a new shell, and try again. The difference between the variables is explained in The difference between ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY.
429 — two different kinds of 429
The number is the same, but the causes are completely different. If you’re using a subscription, you’ve hit the session window limit, and there’s no option but to wait for the window to reset — upgrading to a higher plan won’t help in that moment. If you’re using an API key, you’ve hit a requests-per-second or token-throughput limit; exponential backoff retries usually fix it.
You can tell which applies by checking whether ANTHROPIC_BASE_URL is set. If it is, you’re using a key, not a subscription. Claude Code pricing covers subscription limits, how they work, and your options when you hit one.
529 overloaded_error — an error that isn’t your problem
529 means the upstream model server is temporarily overloaded. The request content, key, and balance aren’t to blame, so changing settings won’t fix this error. Retrying is the only remedy, and exponential backoff has a much higher success rate than an immediate retry.
Using a gateway with automatic fallback reduces how often you notice the error, because it routes requests elsewhere when one upstream returns a 529. For a detailed explanation for English-speaking readers, see Handling 529 overloaded_error.
Continue working after hitting your subscription limit
If the 429 is due to your subscription, you can switch just that session to a key instead of waiting. You don’t need to cancel your subscription — usage is billed to the key only while the two variables below are set; remove them to switch back.
# Claude Code를 구독 대신 API 키로 돌릴 때 쓰는 두 줄.
# 이 두 변수가 설정돼 있는 동안에는 구독 한도가 적용되지 않습니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
# Claude Code의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 가리키므로,
# Kunavo가 아직 제공하지 않는 모델이 호출돼 404가 나지 않도록 모델을 고정합니다.
# sonnet 별칭이 부르는 Sonnet 5.5는 Kunavo가 제공하지 않아, 고정하지 않으면
# /model sonnet, opusplan의 실행 단계, sonnet으로 지정한 서브에이전트에서 404가 납니다.
# Opus 5.5는 Claude Code v2.1.280 이상이 필요합니다(이전 버전이면 claude update로 업데이트).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
# 백그라운드 작업을 가장 싼 모델로 보내는 한 줄 — 매 세션 효과가 있습니다.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5Rates are read directly from the catalog: Claude Sonnet 5 costs $1.40 / $7.00 per 1M tokens, and Claude Haiku 4.5 costs $0.70 / $3.50. Charges come from your prepaid balance, so months when you don’t use it cost nothing. Claude API pricing and payments explains payment methods and how to register a local card.
Installation errors are a separate issue
Installation problems are usually caused by the Node.js version or global installation permissions, and are a different category from the three errors above. First, check whether claude --version prints normally. If it does, installation is complete, and any subsequent problem is related to authentication or the network. Mixing up these two categories is the biggest time sink.
Frequently asked questions
Why does Claude Code return a 401 error?
Most of the time, the authentication header was sent incorrectly; the key itself is rarely wrong. Claude Code sends ANTHROPIC_AUTH_TOKEN as Authorization: Bearer and ANTHROPIC_API_KEY in the x-api-key header. If you swap the two variables, you’ll get a 401 even if the key is valid. When using a gateway, ANTHROPIC_AUTH_TOKEN is the right one. If both variables are set, remove one and open a new shell.
How do I fix persistent 429 errors in Claude Code?
A 429 is a rate limit, and there are two possible causes. If you’re using a subscription, you’ve hit the session window (rolling window) limit, and there’s no option but to wait for the window to reset. If you’re using an API key, you’ve hit a requests-per-second or token-throughput limit; retrying with exponential backoff usually fixes it. To tell which applies, check whether ANTHROPIC_BASE_URL is set — if it is, you’re using a key, not a subscription.
Is a 529 overloaded_error my problem?
No. A 529 overloaded_error means the upstream model server is temporarily overloaded; it has nothing to do with your request or key. Retrying is the only remedy, and exponential backoff has a much higher success rate than an immediate retry. Using a gateway with automatic fallback reduces how often you notice the error, because it routes the request elsewhere when one upstream returns a 529.
How do I fix Claude Code installation errors?
Installation errors are usually caused by the Node.js version or global installation permissions, and are unrelated to the API or key. Their causes are completely different from errors that occur after installation, so first determine which kind you’re dealing with: if claude --version prints normally, installation is complete, and subsequent problems are related to authentication or the network.
How can I tell whether an error is a client issue or a server issue?
Send a request directly to the endpoint. Use curl to send a minimal request to /v1/messages: if you get a 200, the key and address are working, and the remaining issue is Claude Code configuration. A 401 indicates an authentication problem, a 429 a rate limit, and a 529 upstream overload. This single request narrows the cause down to three possibilities, so it’s the fastest first step before changing settings at random.
Can I continue working with an API key after hitting my subscription limit?
Yes, and you don’t need to cancel your subscription. Set ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN, and that shell will bill usage to the key instead of the subscription. Remove the variables to switch back. At Kunavo rates, Claude Sonnet 5 costs $1.40 / $7.00 per 1M tokens, and Claude Haiku 4.5 costs $0.70 / $3.50; charges come from your prepaid balance, so months when you don’t use it cost nothing.