Claude Code 속도 제한, 500, 529 과부하 및 API 키 문제 해결
API 키 설정, Pro·Max와 API 결제의 차이, Messages 호환 엔드포인트, 속도 제한, 서버 오류와 경로 과부하를 다루는 점검 안내입니다.
오류를 진단할 때 확인할 질문
커뮤니티 토론으로 조사 방향을 찾고 실제 한도, 계정 상태와 오류 의미는 공식 문서와 요청 로그로 확인하세요.
코딩 중 속도 제한 발생
계정, 워크스페이스, 모델 경로 또는 게이트웨이 중 어디의 제한인가요?
계정 한도를 확인하고 동시 실행과 컨텍스트를 줄여 재시도하세요.API 키와 Pro·Max 구독의 차이
현재 인증이 구독 이용 권한을 쓰나요, API 결제를 쓰나요?
공급업체가 명시적으로 연계하지 않았다면 구독 권한과 API 결제를 따로 확인하세요.에이전트 루프 중 500 또는 529 발생
공급업체 과부하, 게이트웨이 경로 문제 또는 반복 재시도 루프인가요?
코드 변경 전에 상태, 요청 ID, 경로, 모델, 토큰 수와 재시도 횟수를 기록하세요.상태 코드부터 확인하세요
키·권한 문제, 사용 한도, 서버 오류, 과부하를 구분한 뒤 해결 방법을 선택하세요.
속도 제한 도달
계정, 워크스페이스, 모델 또는 경로의 요청 수나 토큰 한도를 초과했습니다.
- 에이전트 동시 실행 축소
- 긴 컨텍스트 줄이기
- 대기 간격을 늘려 재시도
- 잔액과 모델 한도 확인
API 서버 오류
공급업체나 경로에서 서버 측 오류를 반환했습니다. 반복되면 경로 관련 기록이 필요합니다.
- 요청 ID 기록
- 대기 후 한 번 재시도
- 반복되면 다른 경로와 비교
- 먼저 프롬프트부터 고치지 않기
과부하
상위 서비스의 부하가 높습니다. API 키를 바꾸는 것만으로는 보통 해결되지 않습니다.
- 대기 간격 늘리기
- 대체 모델 시도
- 요청 크기 축소
- 서비스 상태와 지원 채널 확인
API 키 또는 권한 문제
현재 키가 잘못되었거나 모델 또는 엔드포인트 접근 권한이 없을 수 있습니다.
- ANTHROPIC_API_KEY 확인
- 기본 URL 확인
- 모델 접근 권한 확인
- 실제 결제 계정 확인
코드를 바꾸기 전에 사실을 수집하세요
- 정확한 오류, HTTP 상태, 모델, 엔드포인트와 시간을 기록하세요.
- Anthropic 직접 키를 쓰는지 호환 게이트웨이를 쓰는지 확인하세요.
- API 결제와 한도를 Pro·Max 구독 상태와 별도로 점검하세요.
- 429이면 동시 실행과 컨텍스트 크기를 먼저 줄이세요.
- 500 또는 529이면 대기 후 한 번 재시도하고 다른 경로나 대체 모델과 비교하세요.
- 게이트웨이에서는 Messages 엔드포인트, 모델 경로, 캐시 동작과 지원 안내를 확인하세요.
Pro·Max 이용 권한과 API 결제는 다릅니다
현재 키, 기본 URL과 결제 계정을 확인하세요. 구독 이용 권한과 API 잔액이 같다고 가정하지 마세요.
API 이용 시작게이트웨이를 쓴다면 Messages 엔드포인트를 확인하세요
Claude 호환 클라이언트에는 올바른 Messages 엔드포인트, 유효한 키와 실제 작업을 지원하는 모델 경로가 필요합니다.
문서 확인Claude Code API 오류
왜 Claude Code가 속도 제한 도달을 표시하나요?
요청, 토큰 또는 모델 경로 한도를 초과했습니다. 현재 키, 워크스페이스, 경로, 컨텍스트와 에이전트 동시 실행 수를 확인하세요.
Pro·Max에 API 키가 포함되나요?
공식 계정 페이지에 별도 안내가 없다면 구독 권한과 API 결제를 따로 확인하세요. 현재 인증 방식과 결제 계정을 확인해야 합니다.
API Error 500이면 어떻게 하나요?
요청 ID를 기록하고 대기 후 한 번 재시도하세요. 반복되면 다른 경로와 비교하거나 시간, 모델, 요청 ID를 지원팀에 전달하세요.
529 overloaded는 무슨 뜻인가요?
상위 서비스가 과부하 상태입니다. 기다리거나 재시도 간격을 늘리고 요청을 줄이거나 대체 경로를 쓰세요. 키 교체만으로 과부하 자체가 해결되지는 않습니다.
현재 규칙을 확인할 곳
한도와 오류 의미는 공식 문서를 기준으로 확인하세요. 커뮤니티 토론은 조사 단서이지 검증된 사실을 대체하지 않습니다.