코딩 세션 중 요청 한도
계정, 워크스페이스, 모델 또는 경로가 허용량보다 많은 요청이나 Token을 보내고 있습니다.
병렬 Agent 실행 줄이기 · 긴 컨텍스트 줄이기Claude Code API 문제 해결
Claude Code 요청 한도, 500, 529 과부하 및 API Key 혼동 해결
API Key 설정, Pro·Max와 API 과금의 차이, Messages 호환 엔드포인트, 요청 한도, 서버 오류 및 과부하 경로를 한 번에 확인하는 절차입니다.
claude-code-diagnostics
$ claude-code run --model claude-sonnetAPI Error: 요청 한도 도달status=429 route=messages tokens=128k retries=3다음: 동시 실행을 줄이고 Key를 확인한 뒤 백오프로 재시도
4 오류 유형1 절차0 내용이 부족한 페이지
커뮤니티 신호
개발자가 공개적으로 반복해서 묻는 내용
Reddit과 X에서 반복되는 패턴을 안정적이고 검증 가능한 문제 해결 안내로 정리했습니다.
API Key와 Pro·Max 구독의 차이
활성 Key, Base URL과 과금 출처를 확인하세요. 구독과 API 크레딧이 같은 잔액을 쓴다고 가정하지 마세요.
모델 액세스 확인 · 구독 로그인과 API 과금 구분Agent 루프의 500 또는 529 오류
공급자 또는 경로에서 서버 측 오류를 반환했습니다. 한 번의 재시도는 가능하지만 반복되면 라우팅 근거가 필요합니다. 상위 서비스의 부하가 높습니다. 일반적으로 API Key를 바꿔도 해결되지 않습니다.
request id 기록 · 백오프오류 지도
소문이 아닌 상태 코드부터 확인하세요
Key, 쿼터, 서버 오류와 과부하를 분리하는 것이 가장 빠른 해결 방법입니다.
429
요청 한도 도달
계정, 워크스페이스, 모델 또는 경로가 허용량보다 많은 요청이나 Token을 보내고 있습니다.
- 병렬 Agent 실행 줄이기
- 긴 컨텍스트 줄이기
- 백오프로 다시 시도
- 현재 쿼터와 모델 한도 확인
500
API 서버 오류
공급자 또는 경로에서 서버 측 오류를 반환했습니다. 한 번의 재시도는 가능하지만 반복되면 라우팅 근거가 필요합니다.
- request id 기록
- 한 번만 재시도
- 반복되면 경로 전환
- 처음부터 프롬프트를 다시 쓰지 않기
529
과부하
상위 서비스의 부하가 높습니다. 일반적으로 API Key를 바꿔도 해결되지 않습니다.
- 백오프
- 대체 모델 사용
- 요청 크기 줄이기
- 지원 및 상태 채널 확인
401/403
API Key 또는 권한 문제
Claude Code가 예상한 Key를 사용하지 않거나 요청한 모델 또는 엔드포인트에 대한 권한이 없습니다.
- ANTHROPIC_API_KEY 확인
- Base URL 확인
- 모델 액세스 확인
- 구독 로그인과 API 과금 구분
확인 절차
코드를 변경하기 전에 다음 정보를 수집하세요
- 정확한 오류 문구, HTTP 상태, 모델, 엔드포인트와 시각을 기록합니다.
- Claude Code가 Anthropic 직접 Key와 호환 게이트웨이 Base URL 중 무엇을 사용하는지 확인합니다.
- API Key 과금과 쿼터를 Claude Pro 또는 Max 상태와 별도로 확인합니다.
- 429에서는 공급자를 바꾸기 전에 동시 실행 수와 컨텍스트 크기를 줄입니다.
- 500 또는 529에서는 백오프로 한 번 재시도한 뒤 다른 경로나 대체 모델과 비교합니다.
- 게이트웨이에서는 Messages 호환 엔드포인트, 모델 경로, 캐시 및 지원 페이지를 확인합니다.
Pro 또는 Max는 API 과금과 다릅니다
활성 Key, Base URL과 과금 출처를 확인하세요. 구독과 API 크레딧이 같은 잔액을 쓴다고 가정하지 마세요.
API 액세스 받기게이트웨이를 사용하나요? Messages 엔드포인트를 확인하세요
Claude Code 계열 클라이언트에는 일반적으로 Messages 호환 엔드포인트, 유효한 API Key와 적절한 모델 경로가 필요합니다.
문서 열기FAQ
Claude Code API 오류
Claude Code가 요청 한도에 도달했다고 표시하는 이유는?
계정, 워크스페이스, 모델 또는 경로가 허용량보다 많은 요청이나 Token을 보내고 있습니다. 병렬 Agent 실행 줄이기 · 긴 컨텍스트 줄이기 · 백오프로 다시 시도 · 현재 쿼터와 모델 한도 확인
Claude Pro 또는 Max에 API Key가 포함되나요?
활성 Key, Base URL과 과금 출처를 확인하세요. 구독과 API 크레딧이 같은 잔액을 쓴다고 가정하지 마세요.
API Error 500은 어떻게 처리하나요?
공급자 또는 경로에서 서버 측 오류를 반환했습니다. 한 번의 재시도는 가능하지만 반복되면 라우팅 근거가 필요합니다. request id 기록 · 한 번만 재시도 · 반복되면 경로 전환 · 처음부터 프롬프트를 다시 쓰지 않기
529 overloaded는 무엇을 의미하나요?
상위 서비스의 부하가 높습니다. 일반적으로 API Key를 바꿔도 해결되지 않습니다. 백오프 · 대체 모델 사용 · 요청 크기 줄이기 · 지원 및 상태 채널 확인
출처
현재 규칙을 확인할 곳
한도와 오류 의미는 공식 문서에서 확인하세요. 커뮤니티 토론은 수요를 보여주지만 공식 정보원은 아닙니다.