Claude Code 상세 사용법 55: 런타임 에러를 복구 루프로 분류하기 | DAKER 커뮤니티

Claude Code 상세 사용법 55: 런타임 에러를 복구 루프로 분류하기

Claude Code 에러를 보면 바로 “다시 시도”를 누르고 싶지만, 선임 엔지니어의 첫 반응은 분류입니다. 공식 error reference는 5xx, 529, timeout, 429, usage limit, auth, network, request error를 구분합니다. 클로드 코드 장애 대응은 에러 문구를 복사한 뒤 어떤 계층의 문제인지 나누는 것에서 시작합니다.

Mermaid 흐름으로 보는 에러 분류

아래 Mermaid source처럼 provider, quota, credential, request shape를 먼저 나누면 불필요한 설정 변경을 줄일 수 있습니다.

Mermaid source:
flowchart TD
  A[Claude Code error] --> B{Error family}
  B --> C[5xx or 529: retry/status]
  B --> D[429 or limit: reduce load]
  B --> E[Auth: check credential]
  B --> F[Request: shrink or fix input]

5xx, 529, timeout은 내 프롬프트부터 의심하지 않는다

500과 529는 보통 provider capacity나 temporary server issue입니다. Claude Code는 transient failure를 자동 retry한 뒤에 에러를 보여줍니다. 529는 사용량 한도가 아니라 capacity 문제입니다. 몇 분 뒤 재시도하거나 /model로 다른 모델을 선택합니다.

/model
try again with the same task, but keep the scope unchanged

timeout은 큰 응답이나 느린 network에서도 생깁니다. 긴 작업은 작은 prompt로 쪼개고, proxy나 network가 원인이면 timeout 환경 변수를 조정할 수 있습니다.

429와 사용량 제한은 다르다

Request rejected (429)는 API key, Bedrock, Vertex 같은 provider rate limit일 수 있습니다. 먼저 /status로 현재 credential이 무엇인지 봅니다. 의도치 않게 낮은 tier API key가 환경 변수로 잡혀 있으면 subscription session이 아니라 그 key로 요청될 수 있습니다.

/status
/usage

병렬 subagent를 많이 돌리는 중이라면 concurrency를 줄이고, scripted run은 작은 모델이나 낮은 동시성으로 조정합니다. “Server is temporarily limiting requests”는 plan quota와 별개인 일시적 throttle일 수 있습니다.

인증 에러는 credential source를 먼저 본다

Not logged in, invalid API key, org disabled, subscription access disabled 같은 에러는 Claude Code가 누구로 요청하는지 증명하지 못하는 상태입니다. interactive session에서는 /login이 기본 복구입니다. CI와 CLI 자동화에서는 interactive login 대신 ANTHROPIC_API_KEY나 apiKeyHelper처럼 명시적인 인증 경로가 필요합니다.

claude auth status --text

조직 정책으로 API key auth나 subscription access가 막힌 경우에는 프롬프트를 바꿔도 해결되지 않습니다. 관리자 정책과 provider 설정을 확인해야 합니다.

request error는 입력 형태를 줄인다

Prompt is too long, Request too large, image too large, PDF password protected, tool use block mismatch 같은 문제는 요청 모양의 문제입니다. 큰 로그는 파일 경로로 넘기고, 파일은 line range나 함수 단위로 읽게 합니다. compaction error는 /compact나 /clear로 context를 줄입니다.

이 로그 전체를 붙여 넣지 말고, error section이 있는 파일 경로와 200줄 범위만 분석해줘.

1M context 관련 entitlement error는 model picker에서 standard context variant로 바꾸거나 usage credits 설정을 확인합니다. 이 부분은 계정과 plan에 묶이므로 확정적인 가격 설명보다 현재 에러 메시지와 /usage 결과를 기준으로 판단합니다.

실패 모드

모든 에러를 “Claude가 못했다”로 묶으면 복구가 느립니다. 529에 prompt를 줄이거나, auth error에 /compact를 하거나, request too large에 model switch만 하는 식의 대응은 효과가 없습니다. 에러 family, active credential, prompt size, concurrency, provider status를 한 줄씩 기록하세요.

시니어 엔지니어의 결론

Claude Code 에러 대응은 재시도 버튼이 아니라 runbook입니다. 5xx와 529는 provider 상태, 429와 limit은 quota와 concurrency, auth는 credential source, request error는 입력 크기와 형식으로 나눕니다. 이렇게 해야 코드 리뷰, 테스트 자동화, MCP 연결, CLI 자동화 같은 AI 코딩 루프가 장애를 만나도 다음 행동이 명확해집니다.

참고: Anthropic Claude Code error reference, troubleshooting, llms.txt 문서를 2026-06-12 Asia/Seoul 기준으로 확인했습니다.