문제 해결
Claude Code API 오류 — 429, 401, 402, 529 해결
Claude Code는 API 실패를 "API Error:"로 시작하는 한 줄과 원본 응답 본문으로 표시합니다. 아래 페이지는 각 형태의 정확한 텍스트, 발생 이유, 해결 방법을 다룹니다.
| 오류 | 의미 |
|---|---|
API Error: 429 {"type":"error","error":{"type":"rate_limit_error… | Claude Code는 분당 처리량이 소진되면 API Error: 429 rate_limit_error를 출력합니다. 이 한도가 실제로 무엇인지, 병렬 에이전트가 왜 이를 유발하는지, 어떻게 해결하는지 설명합니다. |
API Error: 401 {"type":"error","error":{"type":"authentication_e… | Claude Code는 키가 통신 대상 엔드포인트에 도달하지 못하면 API Error: 401 invalid x-api-key를 출력합니다. 이를 유발하는 환경 변수 규칙과 해결 방법. |
API Error: 529 {"type":"error","error":{"type":"overloaded_error… | Claude Code는 업스트림 용량이 포화되면 API Error: 529 Overloaded를 출력합니다. 왜 당신의 요청 탓이 아닌지, 왜 몰려서 발생하는지, 실제로 도움이 되는 것은 무엇인지 설명합니다. |
API Error: 402 {"type":"error","error":{"type":"billing_error","… | 선불 잔액이 요청을 감당하지 못하면 Claude Code는 API Error: 402 billing_error를 출력합니다. 충전하세요. 402를 레이트 리밋처럼 재시도하지 마세요. |
Claude Code API Error 429 (rate_limit_error) 원인과 해결 방법
Claude Code는 분당 처리량이 소진되면 API Error: 429 rate_limit_error를 출력합니다. 이 한도가 실제로 무엇인지, 병렬 에이전트가 왜 이를 유발하는지, 어떻게 해결하는지 설명합니다.
Claude Code API Error 401 invalid x-api-key 해결 방법
Claude Code는 키가 통신 대상 엔드포인트에 도달하지 못하면 API Error: 401 invalid x-api-key를 출력합니다. 이를 유발하는 환경 변수 규칙과 해결 방법.
Claude Code API Error 529 Overloaded 의미와 대처 방법
Claude Code는 업스트림 용량이 포화되면 API Error: 529 Overloaded를 출력합니다. 왜 당신의 요청 탓이 아닌지, 왜 몰려서 발생하는지, 실제로 도움이 되는 것은 무엇인지 설명합니다.
Claude Code API Error 402 billing_error — 잔액 부족
선불 잔액이 요청을 감당하지 못하면 Claude Code는 API Error: 402 billing_error를 출력합니다. 충전하세요. 402를 레이트 리밋처럼 재시도하지 마세요.