Claude Code가 API Error: 500을 띄우면, 가장 먼저 피해야 할 것은 “한 번 더”를 반복하는 습관입니다. 이 오류는 하나의 universal retry message가 아닙니다. 실제로는 Anthropic 쪽 live incident, login 또는 OAuth 실패, 깨진 resumed session, 예상과 다른 auth route라는 최소 네 가지 분기가 있고, 각 분기는 첫 조치가 다릅니다.
Status가 빨갛다면 대개 더 많은 로컬 설정 변경이 아니라 기다림이 맞습니다. Status가 초록색이어도, 다음 행동이 같은 재시도일 이유는 없습니다. login path를 다시 확인하거나, 새 session을 열거나, Claude Code가 지금 어느 auth owner로 요청을 보내는지 확인하는 편이 훨씬 더 많은 정보를 줍니다.
이 페이지가 좁게 설계된 이유도 같습니다. Internal server error는 작업 중간뿐 아니라 login 중에도 나타날 수 있고, Status가 회복된 뒤에도 오래된 resumed session만 계속 깨져 있을 수 있습니다. 그래서 이 글은 usage, billing, install 문제를 한데 설명하지 않고, API Error: 500을 가장 빨리 올바른 분기로 되돌리는 데만 집중합니다.
한 번의 branch-specific 수정 후에는 반드시 같은 경로를 다시 검증하세요. 초록 Status 아래에서도 같은 경로가 계속 실패한다면, request_id, /status, /debug를 확보한 뒤 깨끗하게 escalation 하는 편이 낫습니다.
Start Here: Which 500 Branch Are You In?
증상은 좁아 보여도 첫 판단은 좁지 않습니다. Anthropic API docs는 HTTP 500을 api_error, HTTP 529를 별도의 overloaded_error로 정의합니다. 이것은 기본선으로 유용하지만, 실제 복구 순서를 정해 주지는 않습니다. 지금 기다려야 하는지, 다시 login 해야 하는지, 새 session을 열어야 하는지, 아니면 Claude Code가 실제로 어떤 route를 쓰는지 봐야 하는지는 별도로 판단해야 합니다.
| 지금 보이는 현상 | 가장 가능성 높은 owner | 가장 안전한 첫 단계 | 같은 경로에서 무엇을 확인할지 | 언제 escalation 할지 |
|---|---|---|---|---|
| Claude Status가 빨갛거나 새 incident가 열려 있음 | Anthropic 측 incident, auth outage, platform 불안정 | 로컬 설정 변경을 멈추고 회복을 기다린다 | incident 종료 후 같은 failing path를 다시 시도한다 | 초록으로 돌아와도 같은 path가 계속 500을 낸다 |
login 또는 OAuth 중 Internal server error가 발생 | OAuth 만료, auth degradation, clock skew, local credential state 손상 | /status를 보고 /login, 필요하면 claude doctor | 같은 login path가 실제로 회복됐는지 확인 | 초록 status route에서도 login path가 실패 |
| Status는 초록인데 하나의 resumed session만 계속 실패 | 깨진 session state 또는 stale context | 오래된 session 대신 fresh session을 시작 | 같은 task를 새 session에서 다시 실행 | 새 session도 똑같이 실패 |
| Claude Code가 API key, proxy, 다른 provider route를 쓰는 것 같음 | ANTHROPIC_API_KEY override, route mismatch, unexpected auth owner | /status, env, route config를 확인 | known-good path에서 같은 request를 비교 | 같은 route가 fresh credentials에서도 실패 |
이 분기 보드가 이 페이지의 핵심입니다. 커뮤니티 답변은 많은 경우 모든 500을 “Anthropic이 내려갔다” 또는 “조금 있다가 다시 해라”로 압축합니다. 하지만 지금 당장 복구해야 하는 독자에게는 그것만으로는 부족합니다. incident는 실제 분기이지만 유일한 분기는 아닙니다.
If Claude Status Shows an Incident Right Now
Status를 먼저 보는 이유는 불필요한 로컬 디버깅을 줄이기 위해서입니다. Claude Status는 2026-04-10 확인 시점에는 초록이었지만, 상태 이력에는 2026-04-08부터 2026-04-09 사이 authentication, Claude Code, Claude.ai, elevated error rates 관련 incident가 기록돼 있었습니다. 중요한 것은 날짜 자체보다, 이 정확한 API Error: 500 증상이 실제 platform incident와 연결될 수 있다는 점입니다.
실무 규칙은 짧습니다. 관련 컴포넌트가 빨갛다면 로컬 설정을 더 바꾸지 마세요. reinstall, route 전환, 설정 총교체를 incident 중에 하면 빨리 고치기보다 노이즈를 더 만들기 쉽습니다. incident가 끝난 뒤 이전에 실패했던 같은 path를 다시 확인해야 합니다. 같은 path를 써야 incident가 전부였는지, 아니면 다른 분기가 남아 있는지 알 수 있습니다.
여기서 500과 529도 분리해서 기억하는 편이 좋습니다. 두 코드 모두 사용자에게는 “지금 플랫폼이 불안정하다”처럼 보일 수 있지만, docs 상으로는 अलग branches입니다. 나중에 support로 넘길 때도 이 구분이 그대로 가치가 됩니다.
하지만 이 분기를 universal explanation으로 만들면 안 됩니다. Status가 계속 초록이라면 다음 단계는 더 오래 기다리는 것이 아니라 branch diagnosis입니다. incident-aware 하다는 것과 모든 걸 incident로 돌린다는 것은 다릅니다.
If the Error Appears During Login or OAuth
이 분기는 자주 놓칩니다. 독자는 똑같이 Internal server error를 보기 때문에, 작업 중 실패와 같은 문제라고 생각하기 쉽습니다. 하지만 Claude Code의 current troubleshooting docs는 훨씬 좁은 flow를 제시합니다. 먼저 /status로 active auth method를 확인하고, 다음에 /login으로 session을 새로 고친 뒤, 여전히 repeated prompts나 이상한 동작이 남으면 claude doctor로 machine time, local keychain, 환경 문제를 확인하라는 흐름입니다.
이 순서가 중요한 이유는 login failure와 runtime failure가 같은 recovery job이 아니기 때문입니다. login 중에 실패했다면 유용한 질문은 “Claude Code 전체가 고장 났나?”가 아니라 “auth degradation, expired token, clock skew, damaged local state 중 어느 이유로 login path가 깨졌나?”입니다. 이 글은 그 질문에 바로 답해야 합니다.
순서는 짧아도 충분합니다. /status를 보고, /login을 다시 돌리고, 그래도 이상하면 claude doctor를 봅니다. 이 순서면 OAuth, 시계, keychain 사이를 추측으로만 돌지 않아도 됩니다.
검증 경계도 좁게 가져가야 합니다. 같은 login path를 검증하세요. 다른 surface에서 login이 된다는 사실을 Claude Code 회복의 증거로 쓰면 안 됩니다. 초록 status route에서도 Claude Code의 login path가 재로그인 후 계속 실패한다면, 그때는 clean한 auth-specific support case가 됩니다.
If Status Is Green but the Resumed Session Still Fails
Status가 초록이라고 해서 지금 열려 있는 session이 건강하다는 뜻은 아닙니다. 이게 generic advice가 가장 자주 놓치는 분기입니다. 현재 anthropics/claude-code issue에는 API Error: 500이 resumed session과 묶여 보고된 사례가 있고, context가 무너진 상태에서 새 chat가 도움이 되었다는 힌트가 있습니다. 이것만으로 universal root cause를 증명하지는 않지만, 첫 동작을 바꾸기에는 충분합니다.
여기서 가장 가치 있는 control test는 오래된 session을 지나치게 소중하게 다루지 않는 것입니다. fresh session을 열고 필요한 최소 context만 넣어 같은 task를 다시 실행하세요. fresh session이 통하면, 오래된 session state가 failure source였을 가능성이 높다고 배울 수 있습니다. fresh session도 똑같이 실패하면, session-state branch를 빠르게 제외하고 다음 분기로 갈 수 있습니다.
독자가 가장 시간을 많이 잃는 지점도 여기입니다. Status는 초록이니 기다리는 건 의미 없고, old session은 context를 알고 있으니 계속 두드리게 됩니다. 자연스러운 반응이지만 자주 틀립니다. old context 자체가 문제일 수 있기 때문입니다. 500에서는 똑같은 retry보다 fresh session이 더 좋은 진단 실험입니다.
만약 여기서 실제 문제이 usage exhaustion, shared consumption, billing path confusion이라면, 이 페이지가 그 일을 계속 맡으면 안 됩니다. 그 경우에는 Claude Code usage limit 진단 가이드로 넘어가는 편이 맞습니다.
If You May Be on an API Key, Provider, or Proxy Route
많은 Claude Code 사용자는 이 도구가 항상 subscription OAuth path를 쓴다고 생각합니다. 하지만 Anthropic의 troubleshooting docs는 다르게 말합니다. ANTHROPIC_API_KEY가 있으면 Claude Code는 subscription OAuth 대신 그 key를 사용합니다. 이 한 줄만으로도 “분명 로그인돼 있는데 왜 계속 500이지?”라는 혼란의 상당 부분이 설명됩니다.
그래서 /status가 회복 플로우 앞부분에 있어야 합니다. active auth method가 생각과 다르면, 그 뒤의 결론은 모두 흔들립니다. official status page가 초록이어도 API-key route나 proxy route의 실제 상태를 자동으로 설명해 주지는 않습니다. provider나 proxy의 failure는 official route와 다른 방식으로 나타날 수 있습니다.
여기서 안전한 행동은 바로 다른 provider로 도망가는 것이 아닙니다. active route를 확인하고, stale credentials와 unexpected key를 정리한 뒤, 같은 request를 known-good path에서 비교하세요. 의도치 않은 ANTHROPIC_API_KEY를 제거하거나 intended auth owner로 되돌렸더니 문제가 사라지면, 진짜 branch는 route mismatch였습니다. 같은 route가 fresh credentials에서도 실패한다면 그때 비로소 sharper escalation case가 됩니다.
이 section도 install problem까지 넓히지 않는 편이 좋습니다. 본질이 broken local setup, missing prerequisites, first-time configuration이라면, Claude Code install 가이드로 옮겨 가는 쪽이 독자 작업에 더 맞습니다. routing은 한 페이지 만능화를 위한 핑계가 아닙니다.
Verify the Fix and Know When to Escalate
Anthropic API docs는 error responses에 request_id, 일반 responses에 request-id header가 붙는다고 설명합니다. 얻을 수 있으면 남겨 두세요. Claude Code current docs에서는 /status, /debug, /cost도 diagnostic surface로 쓸 수 있습니다. 큰 packet이 필요한 것은 아닙니다. support가 “어느 분기를 이미 테스트했는지” 알 수 있을 정도의 clean evidence면 충분합니다.
에스컬레이션 전에, 같은 failing path에서 다음을 모아 두면 됩니다.
- exact error string과 있다면
request_id또는request-id - 실패 시점의
/status가 빨강이었는지 초록이었는지 - 문제가 login 중인지, old resumed session인지, 특정 auth route인지
/debug출력 또는 최소 reproduction steps
이 차이는 큽니다. “Claude Code가 500을 준다”는 약한 보고지만, “초록 status에서 같은 login path가 /login 후에도 실패하고 request_id가 있다”는 바로 쓸 수 있습니다. “초록 status, fresh session은 통과하지만 old resumed session은 계속 500”도 마찬가지입니다. 중요한 것은 길이가 아니라 모호성을 줄이는 것입니다.
에스컬레이션 경계는 명확합니다. 초록 status route에서 같은 path가 가장 작은 branch-specific fix 후에도 계속 실패한다면, 그 지점에서 improvisation을 멈추세요. 그 다음부터는 random retry보다 clean handoff가 더 가치 있습니다.
만약 드러난 branch가 사실 500 recovery가 아니라 usage나 explicit rate limit 이야기라면, Claude Code rate limit 가이드로 이동하는 편이 맞습니다. 그 글은 quota와 cost interpretation을 다루고, 이 글은 500을 먼저 제대로 고치는 데 집중합니다.
Frequently Asked Questions
Claude Code API Error: 500과 529 overloaded_error는 같은 건가요?
아닙니다. Anthropic docs에서 500은 api_error, 529는 overloaded_error입니다. 둘 다 platform instability처럼 느껴질 수 있지만, documented branch는 다릅니다.
Claude Status가 초록인데 왜 아직도 500이 보이나요?
초록 Status가 제외해 주는 것은 live-incident branch뿐이기 때문입니다. login-path problem, broken resumed session, unexpected auth-route branch는 여전히 남아 있을 수 있습니다.
먼저 Claude Code를 다시 설치해야 하나요?
보통은 아닙니다. 이 증상에서 reinstall은 우선순위가 높지 않습니다. Status, branch test, same-path verification이 먼저입니다.
오래된 session만 실패할 때 첫 테스트는 무엇인가요?
fresh session을 열고 최소 context로 같은 task를 다시 실행하세요. old session state가 원인인지 가장 빨리 확인하는 방법입니다.
support에는 무엇을 보내야 하나요?
exact error text, 있다면 request_id, /status 결과, 테스트한 branch, 최소 reproduction steps입니다. 긴 일반 불만보다 clean branch evidence가 훨씬 유용합니다.
The Working Rule
Claude Code의 API Error: 500은 generic retry message가 아니라 branch-first recovery problem으로 다루는 편이 더 빨리 해결됩니다. Status를 보고, 분기를 고르고, 작게 수정하고, 같은 path로 확인한 다음, 그래도 초록 아래에서 실패하면 evidence와 함께 escalation 하세요.