Claude Code가 500, 반복 529, 또는 “response may be incomplete”를 표시하면 전체 작업을 다시 보내지 마세요. 응답이 끊겼다고 해서 파일 수정, shell command, 외부 쓰기가 전혀 실행되지 않았다는 뜻은 아닙니다. 같은 요청을 재전송하면 완료된 tool call이 두 번 실행될 수 있습니다.
오류 분기를 먼저 정하고, 해당 service path가 회복되기를 기다린 뒤, 같은 session을 resume해 실제 상태를 대조하세요. 그다음에만 continue를 보냅니다. 500은 api_error, 반복 529는 전체 사용자 단위의 capacity overload, mid-response notice는 완료 block은 남고 마지막 block만 잘렸을 수 있다는 뜻입니다.
가장 흔한 함정은 529입니다. Claude Code 문서는 반복 529를 과부하로 설명하며, 개인 사용 한도도 아니고 quota에 잡히는 것도 아니라고 말합니다. 먼저 터미널의 정확한 줄을 아래 분기표에 맞추세요.
| 정확한 문구 | 먼저 볼 분기 | 첫 조치 | 같은 path에서 확인할 것 | 더 깊게 갈 때 |
|---|---|---|---|---|
출력 전 500 | 서비스 측 내부 오류 | Claude Status 확인 후 잠깐 대기 | 같은 session, auth route, model | 공개 incident 없이 같은 path가 실패 |
출력 전 반복 529 | 전체 사용자 capacity overload | status 확인 후 대기; task가 허용할 때만 /model | 같은 session과 route를 cool-down 후 확인 | status와 route 확인 뒤에도 반복 |
Server error mid-response, connection closed, stalled stream | turn 일부가 이미 완료 | 전체 task를 다시 보내지 말고 남은 output과 상태 확인 | 같은 session을 resume하고 확인 후 continue | tool 또는 외부 write 완료 여부를 모름 |
429 | API key 또는 provider 제한 | 대기 창, Console 한도, model 한도, active API 경로 확인 | window 이후 또는 경로 correction 이후 retry | headers나 Console이 한도 소진을 보임 |
| temporary throttle 문구, session 한도, weekly 한도 | Claude Code throttle 또는 usage window | cool down 또는 plan/session window 확인 | window가 바뀐 뒤 같은 workflow 재개 | 문구가 plan 또는 reset window를 명시 |
| plan과 한도가 계정 예상과 다름 | route override | /status, ANTHROPIC_API_KEY, proxy 확인 | intended subscription/API-key route 확인 | 깨끗한 route에서도 같은 오류 분기 |
원인을 추측하기 전에 분기부터 고른다
Claude Code의 error reference는 runtime error를 Claude API code와 연결합니다. 또한 Claude Code는 일부 transient failure를 사용자에게 보여주기 전에 자동 retry합니다. 그래서 터미널에 보이는 오류 줄은 시작점이 아니라, 자동 retry 이후의 판단 지점입니다.
첫 질문은 "Claude가 다운됐나?"도 아니고 "내 quota가 끝났나?"도 아닙니다. 이 줄이 어떤 문서화된 분기에 속하는지입니다. 500은 status 확인, 짧은 대기, 같은 path retry 한 번으로 시작합니다. 반복 529는 capacity branch입니다. 실제 429는 API key, provider, model limits를 봅니다. session/weekly limit는 usage window입니다. route가 이상하면 /status가 먼저입니다.
2026-08-04 확인 시점에 Claude Status는 Claude API와 Claude Code를 operational로 표시했고, history에는 8월 3일에 해결된 model error incidents가 있었습니다. 이 snapshot은 현재 실패 원인을 정하지 않습니다. live status를 본 뒤 session과 실제 state를 확인해야 합니다.
500 분기: status, 짧은 대기, 같은 command 한 번
Anthropic API error docs는 HTTP 500을 api_error로 매핑합니다. Claude Code error reference도 API Error: 500 Internal server error를 infrastructure-side 문제로 다루며 prompt, settings, account가 직접 원인이라고 보지 않습니다.
안전한 순서는 짧습니다.
- Claude Status를 확인합니다.
- 잠깐 기다린 뒤 같은 command 또는 message를 한 번만 retry합니다.
- 검증 중 model, auth route, shell profile, prompt를 동시에 바꾸지 않습니다.
- incident가 없고 같은 path가 계속 실패하면 세부 정보를 보관하고
/feedback또는 support route로 이동합니다.
정확한 증상이 지속적인 API Error: 500이라면 Claude Code API Error 500 가이드로 이어가세요. 여기서는 500을 529나 rate limit처럼 처리하지 않도록 분기만 잡습니다.
529 분기: 과부하이지 usage limit가 아니다
Claude Code 문서는 반복 529를 꽤 명확하게 설명합니다. API가 전체 사용자 단위의 capacity pressure를 받고 있으며, Claude Code가 이미 retry했고, 529는 usage limit도 quota 차감도 아닙니다.
첫 조치는 upgrade가 아닙니다.
- status에서 capacity notice를 확인합니다.
- 몇 분 기다린 뒤 다시 시도합니다.
/model은 task가 다른 model을 받아들일 수 있을 때만 씁니다.- 짧은 cool-down 뒤 같은 session과 route를 확인합니다.
반복 529가 이 확인 뒤에도 돌아오면 Claude Code overloaded error 가이드로 이동하세요. 529 overloaded_error를 429 rate_limit_error처럼 다루면 key, billing, plan 조치로 너무 빨리 가게 됩니다.
새 작업을 만들지 말고 원래 session을 resume한다
현재 Claude Code 오류 문서는 응답 시작 뒤 발생한 실패를 별도 처리합니다. server error mid-response, connection closed, stalled stream이 생기면 완료된 response block은 대화에 남고, 중단된 마지막 block은 버려집니다. 같은 tool call을 두 번 실행할 수 있기 때문에 incomplete notice가 붙습니다.
화면이 남아 있으면 보존된 응답을 먼저 읽으세요. 완료된 edit, command result, test output, deployment step은 실제 state를 확인할 단서입니다. 그 뒤의 계획까지 완료됐다는 보장은 아닙니다. 서비스가 돌아와도 확인 전에 원래 task를 다시 보내지 않습니다.
process가 종료됐다면 작업을 시작한 project directory에서 실행합니다.
bashclaude --continue claude --resume
claude --continue는 current directory의 최근 session, claude --resume은 picker를 엽니다. Session 관리 문서에 따르면 resume은 tool calls와 results를 포함한 history를 복구합니다. 새 session에 기억으로 설명하는 것보다 중복 방지에 필요한 evidence가 더 많이 남습니다.
같은 session을 두 terminal에서 동시에 resume하지 마세요. message가 하나의 transcript에 섞일 수 있습니다. 다른 경로를 시험하려면 명시적으로 fork/branch합니다.
continue 전에 side effect를 대조한다
Conversation은 시도한 내용을 보여 주고, 실제 system of record는 결과를 보여 줍니다.
| 가능한 side effect | 확인할 evidence | 안전한 결정 |
|---|---|---|
| direct file edit | git status --short, git diff -- <path>, file contents | 현재 edit를 유지하거나 의도적으로 되돌리고 같은 edit를 다시 요청하지 않음 |
| Bash가 file 변경 | working tree, generated files, output, timestamp | checkpoint 밖일 수 있으므로 완료 가능성을 전제로 확인 |
| test, build, migration 실행 중 | terminal, process, lock, report, migration table | 기다리거나 명확히 중단하고 두 번째 실행을 만들지 않음 |
| commit / branch 작업 | git status, current branch, git log -1 --oneline | 관찰한 Git state에서 이어감 |
| CI, deployment, ticket, API, DB write | run/deployment/request ID, record, idempotency key | 외부 owner에서 확인하고 stream 끊김을 실패로 추정하지 않음 |
Git은 다음 read-only 확인부터 시작할 수 있습니다.
bashgit status --short git diff --stat git diff git log -1 --oneline
이 명령은 remote state를 증명하지 않습니다. PR, deployment, database, message, payment가 가능했다면 해당 서비스 기록을 직접 확인하세요. local session을 다시 열어도 외부 서비스가 이미 받은 작업은 취소되지 않습니다.
대조가 끝난 뒤 resume한 대화에 범위를 줍니다.
text중단된 turn에서 완료된 tool call을 먼저 정리하고 현재 working tree와 제가 제공하는 외부 state에 대조하세요. command를 재실행하거나 외부 변경을 하지 말고, 다음 단계 하나만 제시한 뒤 확인을 기다리세요.
checkpoint는 local undo이지 transaction log가 아니다
Checkpointing은 direct file-editing tool의 snapshot을 session과 함께 보관하므로 resume 뒤에도 /rewind를 쓸 수 있습니다. 잘못된 edit를 정확히 찾았을 때 유용합니다.
그러나 Bash file change, 대부분의 background subagent edit, session 밖의 동시 편집, 일부 linked path는 보장하지 않습니다. deployment, API, database, message, payment도 되돌리지 못합니다. file history는 Git, remote state는 각 owner의 audit trail로 확인해야 합니다.
무엇을 되돌릴지 확인한 뒤 rewind하세요. blind rewind 뒤 blind replay를 하면 다른 형태의 중복이 생깁니다.
요청 제한 분기: 429, temporary limiting, usage window를 분리
Claude Code에서 "제한"처럼 보이는 문구는 최소 세 가지입니다.
첫째는 실제 API 429 rate_limit_error입니다. API key, provider project, model-specific limits, concurrency, retry-after가 증거입니다. 이 경우 Claude Code rate limit 가이드가 맞는 다음 경로입니다.
둘째는 Server is temporarily limiting requests (not your usage limit)입니다. 이는 짧은 throttle로 보고 cool down 뒤 같은 path를 확인합니다. plan이 소진됐다는 증거가 아닙니다.
셋째는 실제 usage window입니다. session limit, weekly limit, Opus limit, reset time이 보이면 /usage, reset timing, plan window를 봅니다. 이어서 rate-limit reached 가이드 또는 usage limits 진단을 사용하세요.
route override 분기: plan보다 auth 확인이 먼저다
Claude Help는 environment variable의 ANTHROPIC_API_KEY가 authenticated subscription보다 우선할 수 있고, /status로 active auth method를 확인할 수 있다고 설명합니다. 그래서 route check는 부가 단계가 아니라 복구 흐름의 일부입니다.
secret을 노출하지 않는 확인만 하세요.
- Claude Code 안에서
/status를 실행합니다. - shell이나 environment에
ANTHROPIC_API_KEY가 설정됐는지만 확인하고 key 자체는 붙여넣지 않습니다. - subscription auth, direct Anthropic API, Bedrock, Vertex, proxy 중 무엇인지 확인합니다.
- 원래 의도한 route에서 같은 request를 다시 실행합니다.
route를 바로잡았을 때 결과가 바뀌면 실제 문제는 route mismatch였습니다. intended route에서도 같은 분기가 계속되면 support evidence가 더 깨끗해집니다.
에스컬레이션 전에 남길 증거
Anthropic API error response에는 top-level request_id가 있을 수 있고, API response에는 request-id header가 있을 수 있습니다. Claude Code에는 /status, /model, /usage, /feedback도 있습니다.
짧게만 보관하면 됩니다.
500,529,429, 또는 제한 문구 전체가 포함된 정확한 터미널 줄- 실패 시간과 timezone
- 그 시점의 Claude Status
/status의 active route- 사용 model과
/model변경 여부 - same-path retry 결과
- request ID 또는 feedback context
분기를 맞추고, 최소 조치를 했고, 같은 path가 여전히 실패하면 멈추세요. 무작위 retry는 evidence를 흐립니다.
자주 묻는 질문
Claude Code 529는 rate limit인가요?
아니요. 반복 529는 overload로 문서화되어 있습니다. 실제 API rate limiting은 429 rate_limit_error이고, temporary limiting과 plan-window wording은 또 다릅니다.
Claude Code API Error 500에서 먼저 무엇을 하나요?
Claude Status를 확인하고, 잠깐 기다린 뒤, 같은 command 또는 message를 한 번 retry합니다. incident가 없고 같은 path가 계속 실패하면 세부 정보를 남기고 500 가이드나 /feedback로 이동합니다.
Claude Status가 녹색인데도 실패하면요?
녹색 status는 공개 live incident 하나를 제외할 뿐입니다. 정확한 error, active auth route, model, same-path retry result는 여전히 확인해야 합니다.
API key가 subscription을 덮어쓰는지 어떻게 보나요?
Claude Code에서 /status를 실행하고 shell에 ANTHROPIC_API_KEY가 설정되어 있는지 확인합니다. key 자체는 붙여넣지 마세요.
529가 나오면 plan을 업그레이드해야 하나요?
첫 조치로는 아닙니다. 반복 529는 overload branch입니다. upgrade 판단은 명확한 plan-limit 또는 usage-window wording일 때만 합니다.
장애 뒤 같은 task를 다시 보내도 되나요?
incomplete notice가 있으면 안전하지 않습니다. 같은 session을 resume하고 남은 block, local state, remote state를 확인한 뒤 범위가 있는 continue를 보냅니다.
/rewind가 shell command와 deployment도 되돌리나요?
아니요. checkpoint는 지원되는 direct file edit를 위한 안전망입니다. Bash, process, CI, deployment, API, database는 각각 확인해야 합니다.
