Claude Code API Error 500·529 해결: 끊긴 작업을 중복 없이 재개하기

Claude Code 터미널에 아래 문장이 떴다면 응답한 API 내부에서 예상하지 못한 실패가 일어난 것입니다.

API Error: 500 Internal server error. This is a server-side issue, usually temporary — try again in a moment. If it persists, check https://status.claude.com.

Claude Code 공식 오류 문서에 따르면 이 500은 프롬프트, 설정, 계정 때문에 생기는 오류가 아닙니다. 상태 페이지에서 진행 중인 장애를 확인하고, 1분쯤 기다린 뒤 한 번 다시 보내는 것이 첫 조치입니다. 원래 메시지가 대화에 남아 있으므로 긴 요청이라면 try again만 입력해도 됩니다.

다만 Claude가 파일을 고치거나 명령을 실행하던 도중에 끊겼다면, 다시 보내기 전에 이미 끝난 작업부터 확인해야 합니다. 응답이 끊겨도 편집, 명령, 배포는 완료됐을 수 있고, 처음 지시를 그대로 다시 보내면 같은 일이 두 번 실행될 수 있습니다. 같은 500이 로그인 중에 나오거나 재개한 특정 대화에서만 매 턴 반복된다면 원인과 순서가 다르므로 아래 표에서 지금 상황을 먼저 고르세요.

아래 절차는 2026년 10월 5일 기준 Claude Code 공식 오류 문서와 로그인 문제 해결 문서를 바탕으로 합니다. 실제 장애를 재현하거나 복구를 직접 실행한 결과는 아니며, 설치 버전과 사용 중인 제공자에 따라 표시 문구와 복구 동작이 달라질 수 있습니다.

지금 보이는 오류에서 다음 행동을 고르세요

이 표에서 500·529와 응답 중단 여부는 함께 판단해야 합니다. 오류 코드만 보고 도구가 실행되지 않았다고 결론 내릴 수 없습니다. HTTP 상태 코드 없이 Unable to connect to API가 나온다면 서버 오류 이전의 연결 문제이므로 Unable to connect to API 네트워크 점검으로 가세요. Claude Code가 아니라 웹 대화나 직접 API에서 시작한 문제라면 사용 화면별 Claude 내부 서버 오류 대처에서 해당 경로를 먼저 구분합니다.

API Error 500·529가 뜨면 상태 페이지와 자동 재시도부터

Anthropic 직접 경로라면 Claude Status를 봅니다. Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 사용자 지정 게이트웨이를 쓰면 오류 메시지 끝에 안내된 제공자의 상태를 확인하세요. 공식 문서에 따르면 마지막 안내 문장은 설정된 제공자에 따라 달라지고, 사용자 지정 ANTHROPIC_BASE_URL이라면 게이트웨이 호스트가 표시됩니다. 게이트웨이가 HTML 오류 페이지로 응답하면 API Error: 502 Bad Gateway처럼 상태 코드와 페이지 제목이 나옵니다. 403이나 503을 어느 계층이 돌려줬는지는 Claude Code 403·503·529 오류, 발생 위치별 해결법에서 구분합니다.

진행 중인 장애가 없으면 약 1분 기다리고, 반복해도 안전한 요청일 때 다시 보냅니다. 첫 수동 재시도도 같은 오류로 끝나면 반복을 멈추고 문의 자료를 모으는 편이 안전합니다. 제품이 정한 재시도 횟수가 아니라 불필요한 반복을 막기 위한 기준입니다. 공개된 장애 없이 계속 500 에러가 나면 공식 안내대로 /feedback으로 보고합니다.

반복 529는 API 용량 부족입니다. 공식 문서는 529가 개인 사용 한도가 아니며 할당량에서 차감되지 않는다고 설명합니다. 몇 분 기다리거나, 작업을 처리할 수 있는 다른 모델이 있다면 /model로 바꿀 수 있습니다. 모델별로 용량이 관리되므로 전환이 도움이 될 수 있지만, 다른 모델의 성공이 원래 모델의 복구를 증명하지는 않습니다. 대기 시간과 대체 모델 설정은 Claude Code 529 과부하 오류: 기다릴지, 모델을 바꿀지에서 다룹니다.

자동 재시도 문서는 일시적 실패에 지수 백오프로 최대 10회 재시도한다고 설명합니다. 최초 요청까지 합친 총 10회라는 뜻이 아니며, 모든 실패에 같은 횟수가 적용되지도 않습니다. 예를 들어 v2.1.284부터는 생각하기만 완료되고 텍스트·도구 호출이 시작되기 전의 서버 오류나 과부하에 최대 두 번 재시도합니다. 연결 끊김과 멈춘 스트림은 별도 조건을 적용합니다.

재시도 표시가 움직이는 동안 같은 작업을 다른 터미널에서 시작하지 마세요. 최종 오류가 보이면 그 오류에 적용되는 자동 처리는 이미 끝난 상태입니다. 상태 페이지가 정상이어도 개별 요청이 복구됐다는 뜻은 아니므로, 작업 도중이었다면 남은 응답과 실제 작업 결과를 다음 순서로 확인합니다.

로그인 단계의 OAuth 500: 상태 확인 후 로그인 초기화

/login 도중 터미널에 OAuth error: Request failed with status code 500이 나오고, 브라우저의 claude.ai/oauth/authorize 화면에 "Authorization failed — Internal server error"가 표시됐다는 사용자 보고가 GitHub에 여러 건 있습니다. 2026년 3~4월 보고로, 앞서 OAuth error: timeout of 15000ms exceeded가 먼저 나오거나 OAuth error: Failed to fetch user roles: Request failed with status code 500 형태로 나온 경우도 있습니다. 이 단계에서는 아직 작업이 시작되지 않았으므로 완료한 작업을 대조할 필요가 없습니다. 로그인만 다시 성공하면 됩니다.

공식 로그인 문제 해결 문서에는 OAuth 500 전용 해결책이 없습니다. 다음 순서는 사용자 보고, 공식 장애 기록, 공식 로그인 초기화 절차를 묶은 것입니다.

1. 상태 페이지부터 봅니다. 로그인에 영향을 준 장애가 몇 분 만에 끝나는 경우도 있습니다. Claude 상태 기록을 보면 2026년 8월 24일 16:02~16:08 UTC에는 Claude.ai 로그인 장애, 20:00~20:08 UTC에는 Claude.ai 접속 오류가 있었고, 두 건 모두 Claude Code를 구독으로 연결하는 로그인이 포함됐다고 명시돼 있습니다. 장애가 있으면 해소된 뒤 한 번 다시 시도합니다.
2. 장애가 없으면 로그인을 초기화합니다. /logout으로 완전히 로그아웃하고, Claude Code를 닫은 뒤 claude로 다시 시작해 로그인합니다. 브라우저가 자동으로 열리지 않거나 좁은 터미널에서 URL이 줄바꿈돼 클릭할 수 없으면 c 키로 OAuth URL을 복사해 브라우저에 붙여 넣습니다. OAuth error: Invalid code는 로그인 코드가 만료됐거나 복사 중 잘린 경우이므로 브라우저가 열린 직후 빠르게 완료하세요. /logout은 MCP 서버 로그인과 플러그인 비밀 값까지 지우므로 이후 다시 인증해야 합니다.
3. WSL2, SSH, 컨테이너라면 로그인 코드를 붙여 넣습니다. 브라우저가 다른 호스트에서 열리면 리디렉션이 Claude Code의 로컬 콜백 포트에 닿지 못하고, 로그인 후 브라우저에 코드가 표시됩니다. 그 코드를 Paste code here if prompted 입력란에 붙여 넣거나, 붙여 넣기가 반응하지 않으면 표준 입력으로 코드를 읽는 claude auth login을 사용합니다. WSL2에서 브라우저가 아예 열리지 않으면 BROWSER 환경 변수에 Windows 브라우저 경로를 지정할 수 있습니다.
4. 같은 계정이 다른 컴퓨터에서는 로그인된다면 문제 컴퓨터의 방화벽, 프록시, 로컬 콜백 경로를 의심할 만합니다. 2026년 4월 Windows 보고 한 건(#44725)에서는 같은 계정이 다른 컴퓨터에서 정상이었고, 문제 컴퓨터에는 그룹 정책으로 관리되는 인바운드 차단 방화벽이 있었습니다. 단일 보고이므로 확정된 원인은 아닙니다.

로그인은 끝났는데 오류가 이어진다면 /status로 실제 활성 인증 방식을 확인하세요. Claude Code 로그인·인증 문제 해결 문서에 따르면 ANTHROPIC_API_KEY가 있고 이를 승인했다면 Claude Code는 구독 OAuth 대신 그 키를 쓰며, -p 비대화형 실행에서는 키가 있으면 항상 키를 씁니다. 이전 회사나 프로젝트의 오래된 키가 셸 프로필에 남아 있는 경우가 흔합니다.

시스템 시계와 macOS 키체인 점검은 로그인 후에도 계속 다시 로그인하라고 나올 때 해당합니다. 토큰 검증은 정확한 시각에 의존하므로 시스템 시계를 확인하고, macOS에서 claude doctor가 macOS Keychain is not writable 경고를 보이면 security unlock-keychain ~/Library/Keychains/login.keychain-db로 키체인을 연 뒤 /logout과 /login을 실행합니다. 이 두 가지가 OAuth 500의 원인으로 확인된 것은 아닙니다. Login expired, Not logged in, OAuth token revoked처럼 500이 아닌 로그인 메시지는 Claude unable to authenticate 오류의 뜻과 대처에서 다룹니다.

응답 중간에 끊겼다면 남아 있는 도구 결과를 읽으세요

불완전한 응답 안내는 생각하기 이후 텍스트나 도구 호출이 시작됐거나 해당 블록이 완료된 뒤, 전체 응답이 끝나기 전에 실패한 경우를 다룹니다. Claude Code는 원래 요청을 통째로 다시 실행하지 않고 완료한 내용을 보존합니다. 완료한 도구 호출은 실행하고 그 결과에서 진행할 수 있으며, 턴이 끝날 때 중단된 마지막 블록은 버립니다.

따라서 화면에 남은 내용을 두 부분으로 나누어 읽으세요.

• 완료한 결과: 파일을 수정했다는 도구 결과, 명령 출력, 테스트 결과, 생성된 실행 ID 등입니다. 실제 상태를 확인할 출발점입니다.
• 앞으로 하겠다는 계획: “이제 배포하겠습니다” 같은 문장입니다. 실행 완료의 증거가 아닙니다.

완성된 도구 호출이 있는데 마지막 설명만 잘렸다면 실제 작업은 끝났을 수 있습니다. 반대로 도구 이름이나 계획만 보인다면 완료 여부를 알 수 없습니다. 대화가 짧아졌다는 이유로 변경 사항을 되돌리거나 전체 명령을 다시 실행하지 마세요.

비대화형 -p·Agent SDK 실행도 구분해야 합니다. 현재 문서상 주 대화에서 잘린 응답에 텍스트만 있고 도구 호출이 없으면 자동으로 이어 쓰기를 최대 세 번 시도합니다. 이 조건을 파일 변경이나 외부 작업이 있는 모든 중단에 적용해서는 안 됩니다.

원래 세션을 선택해 다시 여는 순서

터미널이 살아 있고 입력을 받는다면 그 대화에서 계속합니다. Claude Code가 완전히 응답하지 않을 때에만 Ctrl+C로 현재 작업 취소를 시도하고, 그래도 반응이 없으면 터미널을 닫고 다시 시작합니다. 이는 공식 문제 해결 안내의 멈춘 명령 대응이며 모든 500에 필요한 조치는 아닙니다.

프로세스가 종료됐다면 원래 작업 디렉터리에서 선택기를 엽니다.

claude --resume

실행 중인 대화 안에서는 /resume으로 선택기를 열 수 있습니다. 시간, 작업 내용과 프로젝트를 보고 중단된 대화가 맞는지 확인하세요. 최근 대화라는 이유만으로 바로 선택하면 다른 작업을 이어갈 수 있습니다. 선택기에서 Ctrl+A를 누르면 이 컴퓨터의 모든 프로젝트로 범위를 넓힐 수 있습니다.

세션 ID를 알고 있다면 아래 명령의 SESSION_ID를 실제 ID로 바꿉니다. 선택기 대신 정확한 대화를 지정하는 방법입니다.

claude --resume SESSION_ID

현재 세션 복구 오류 안내에 따르면 v2.1.223부터 ID 검색은 현재 프로젝트에서 시작한 뒤 이 컴퓨터의 다른 프로젝트도 확인합니다. 이전 버전은 현재 프로젝트와 Git worktree까지만 검색하므로 당시 작업 디렉터리에서 복구해야 합니다. 기록은 로컬에 저장되며 다른 컴퓨터에서 같은 ID를 넣는 것만으로 복구되지는 않습니다.

claude -p 또는 Agent SDK로 만든 세션은 대화형 선택기에 나오지 않습니다. 원래 실행의 JSON 출력에 있는 session_id를 확인해서 지정하세요. 선택기에 없다는 사실만으로 기록이 삭제됐다고 판단하지 마세요. 다시 열린 대화에 이전 작업과 도구 결과가 나타나는지 확인한 뒤 다음 점검으로 넘어갑니다.

파일·백그라운드 작업·외부 기록을 대조합니다

복구한 대화는 무엇을 시도했는지 알려 줍니다. 무엇이 실제로 끝났는지는 현재 파일과 대상 시스템의 기록에서 확인해야 합니다. 중단 직전 작업을 완료·진행 중·미실행·불명확으로 나누어 적으면 다음 행동을 고르기 쉽습니다.

Git 저장소에서는 다음 읽기 전용 명령부터 사용할 수 있습니다. 첫 줄은 현재 디렉터리를 확인하고, 이후에는 브랜치·파일 변경·최근 커밋을 봅니다.

pwd
git status --short --branch
git diff --stat
git diff
git log -3 --oneline

git diff에 보이지 않는 새 파일도 있으므로 git status의 목록과 실제 내용을 확인하세요. 테스트 로그가 없다고 자동으로 재실행하지 말고 기존 프로세스와 출력 위치를 먼저 찾습니다. 데이터베이스 마이그레이션이라면 대상 DB의 적용 기록도 필요합니다.

로컬 Git 확인으로 배포나 메시지 전송까지 증명할 수는 없습니다. 외부 쓰기가 있었다면 해당 서비스에 접근할 수 있는 사람이 기록을 확인해야 합니다. 응답이 사라져도 서버가 요청을 받아 처리했을 수 있습니다. 완료 여부가 불명확한 쓰기는 재전송을 보류하고, 요청 ID나 기존 멱등성 키가 있다면 그 기록부터 조회하세요.

완료한 일은 건너뛰고 남은 단계만 계속하세요

대조가 끝나면 같은 대화에서 continue로 이어갈 수 있습니다. 다만 “처음 요청대로 다시 해 줘”보다 확인된 결과와 남은 범위를 적는 편이 중복 실행을 줄이는 데 도움이 됩니다. 다음은 파일 수정과 테스트는 끝났고 배포는 하지 않은 것으로 확인된 상황의 예시입니다.

중단된 작업을 이어가세요. 현재 파일에서 수정 완료를 확인했고,
기존 테스트 실행도 성공했습니다. 배포 기록은 없으며 배포는 아직 승인하지 않았습니다.
완료한 편집과 테스트는 반복하지 말고 남은 문서 수정만 진행하세요.
현재 상태가 이 설명과 다르면 변경을 멈추고 차이를 알려 주세요.

진행 중인 작업이 있다면 “테스트 실행 ID ○○는 아직 진행 중이므로 기다린 뒤 결과를 사용하세요”처럼 적습니다. 외부 결과를 모르면 “배포 완료 여부는 확인하지 못했으므로 배포를 다시 실행하지 말고 기록 확인부터 하세요”라고 범위를 제한합니다. 예시의 완료 상태를 확인 없이 그대로 붙여 넣으면 안 됩니다.

복구 성공은 오류 메시지가 사라진 것만으로 판단하지 않습니다. 원래 대화가 열렸고, 실제 완료 상태가 정리됐으며, 완료한 일을 반복하지 않고 남은 작업 결과가 나와야 이어가기가 끝난 것입니다. 다시 같은 오류가 나면 새 작업을 여러 개 시작하지 말고 현재 결과와 오류 시각을 보존합니다.

세션 복구가 실패하거나 다른 프로세스가 사용 중이라면

Failed to resume the conversation은 저장된 기록을 읽거나 처리하지 못했다는 뜻입니다. 현재 공식 안내는 메시지에 나온 ID로 다시 복구하도록 권합니다. CLI 선택기에서 실패하면 종료 코드 1로 끝나고, 실행 중인 대화의 /resume이 실패하면 현재 대화는 계속 유지됩니다.

버전이 v2.1.285보다 오래됐고 같은 복구가 계속 실패한다면 claude update 후 다시 복구하는 방법이 안내되어 있습니다. 그래도 실패할 때 새 세션을 시작할 수 있습니다. 이때는 원래 작업 전체를 재실행하지 말고 확인된 파일 변경, 실행 중인 작업, 외부 결과와 남은 단계의 요약을 전달하세요. 새 세션 시작은 기록 복구의 성공과 다릅니다.

No conversation found with session ID라면 ID 오타, 다른 컴퓨터, 기록 삭제 여부를 확인합니다. 기본 기록 보존 기간은 30일이며 실제 보존 설정과 정리 조건에 따라 달라집니다. 삭제된 대화가 반드시 복구된다고 약속할 수 없습니다.

에이전트 보기에서 This session is running in another terminal 또는 다른 실행 중인 Claude 세션이 대화를 사용한다는 메시지가 나오면, 기존 프로세스에서 계속하거나 그 프로세스를 의도적으로 종료한 뒤 엽니다. v2.1.248부터 에이전트 보기는 살아 있는 터미널이 보유한 대화를 두 번째 프로세스로 열지 않도록 막습니다. 모든 실행 방식에서 동시 복구가 자동으로 차단된다고 가정하지 마세요.

백그라운드 세션이 첫 응답을 끝내기 전에 중단되어 This session has no saved transcript가 나오면 상위 대화에서 이어갈 수 있습니다. 이 경우의 claude respawn은 빈 대화로 새로 시작하는 동작입니다. 저장된 작업을 복구하는 명령으로 사용하면 안 됩니다.

재개한 대화만 계속 500 에러가 날 때 새 세션으로 대조하기

재개 자체는 성공했는데, 그 대화에서 무엇을 보내든 매 턴 API Error: 500이 나고 상태 페이지는 정상인 경우가 있습니다. 같은 컴퓨터에서 새 세션은 문제없이 응답한다면 요청 경로보다 그 대화에 저장된 기록 쪽을 의심할 만합니다.

이 판단의 근거는 두 종류입니다. 하나는 GitHub의 사용자 보고입니다. 2026년 5월 보고(#58827, v2.1.50)에서는 크기가 큰 이전 세션을 재개하면 API Error: 500 status code (no body)가 났지만 새 대화는 정상이었고, 보고자는 저장된 기록 안의 빈 생각하기 블록과 빈 도구 결과를 API가 받아들이지 못한 것으로 분석했습니다. 2026년 6월 보고(#70650, v2.1.178)에서는 며칠 동안 이어진 세션이 /rewind 뒤에도 매번 500을 냈고, 새 탭에서 연 다른 세션은 정상이었습니다. 두 건 모두 Anthropic이 원인을 확인한 것은 아닙니다.

다른 하나는 공식 문서의 대조 방법입니다. 오류 문서는 저장된 기록에 실린 내용 때문에 재개한 대화의 매 턴이 실패하던 몇 가지 400 오류에 대해 claude update 후 재개하고, 그래도 계속되면 /clear로 그 내용을 싣지 않은 대화를 시작하라고 안내합니다. 새 대화에서도 오류가 다시 나면 원인은 저장된 대화가 아니라 요청 경로에 있다는 설명입니다. 500에 대해 같은 말을 한 것은 아니지만, 원래 대화와 새 대화를 비교하는 판단 방식은 그대로 쓸 수 있습니다.

순서는 다음과 같습니다.

1. 원래 대화부터 살립니다. claude update로 버전을 올린 뒤 같은 세션 ID로 다시 재개해 한 번 보냅니다.
2. 새 세션으로 대조합니다. 같은 작업 디렉터리에서 claude로 새 세션을 열고 파일을 바꾸지 않는 짧은 질문을 보냅니다. 새 세션도 500이면 저장된 기록 문제가 아니므로 상태 페이지, 제공자나 게이트웨이, /feedback 쪽으로 돌아갑니다.
3. 새 세션만 정상이면 원래 대화에 반복해서 보내지 않습니다. 앞의 점검표대로 파일, 실행 중인 작업, Git, 외부 기록을 대조한 뒤, 확인된 상태만 새 세션에 넘깁니다.

새 세션에 원래 지시를 그대로 다시 보내면 이미 끝난 편집이나 배포가 다시 실행될 수 있습니다. 확인한 내용만 적어 인계하세요. 아래는 형식 예시이므로 각 항목을 실제로 확인한 상태로 바꿉니다.

이전 세션(SESSION_ID)에서 하던 작업을 이어받습니다. 그 세션은 재개 후 매 턴 500 오류가 나서 더 쓰지 않습니다.
확인된 완료 상태: src/auth의 수정과 단위 테스트 통과(현재 파일과 git diff로 확인).
진행 중: 없음. 확인하지 못한 것: 스테이징 배포 여부 — 다시 배포하지 말고 기록부터 확인하세요.
남은 단계: README의 설정 절 수정.
현재 파일이 이 설명과 다르면 변경을 멈추고 차이를 알려 주세요.

실패하는 대화의 세션 ID, 오류 시각, 새 세션 대조 결과는 남겨 두고 /feedback으로 보고합니다. 저장된 기록 파일을 직접 고치거나 ~/.claude 폴더를 지우거나 외부 세션 복구 도구를 쓰지 마세요. 원래 기록을 잃으면 다시 재개할 수 있는 수단도 함께 사라집니다.

/rewind는 확인된 잘못된 편집을 되돌릴 때 사용합니다

서버 오류가 났다는 이유로 바로 /rewind를 실행할 필요는 없습니다. 원하는 수정까지 지우면 완료한 일을 다시 해야 할 수 있습니다. 먼저 잘못된 파일과 되돌릴 지점을 정하고, 복원 결과를 실제 파일 및 Git 변경과 비교하세요.

현재 코드 복원 오류 안내는 일부 또는 전부 복원되지 않는 경우를 구분합니다. 링크나 일반 파일이 아닌 경로, 체크포인트 이후 달라진 디렉터리, 안전하게 읽지 못하는 백업은 건너뛸 수 있습니다. Restored the code, but skipped … files라면 건너뛴 파일의 현재 내용은 그대로 남습니다. No files were restored라면 아무 파일도 복원되지 않았습니다.

백업이 없어진 경우에는 다시 같은 복원을 시도해도 해결되지 않습니다. 버전 관리에서 되돌리거나 현재 변경을 확인해 필요한 편집만 수정해야 합니다. /rewind를 모든 셸 변경·백그라운드 작업·배포·DB 변경을 취소하는 수단으로 삼지 마세요. 외부 작업의 결과는 해당 시스템에서 확인하고 별도의 취소 또는 복구 절차를 선택합니다.

사용 한도라면 초기화 시각과 적용 범위를 확인하세요

529와 개인 한도를 혼동하면 기다릴 이유와 모델을 바꿀 이유가 뒤섞입니다. 공식 사용 한도 안내에서 세션·주간 한도는 모든 모델이 공유합니다. 따라서 /model만 바꿔도 다시 열리는 한도가 아닙니다. Opus·Sonnet 한도는 해당 모델 계열에만 적용되므로 제공되는 다른 계열로 바꿔 계속할 수 있습니다.

/usage와 오류에 나온 초기화 시각을 기준으로 판단하세요. v2.1.234부터 claude.ai 구독으로 로그인한 대화형 CLI는 열린 세션에서 초기화를 기다렸다가 중단된 작업을 이어갈 수 있습니다. 자동 이어가기가 켜져 있다면 별도 수동 재전송을 겹치지 않게 확인합니다. 데스크톱 앱의 세션 한도 카드 체크박스와 CLI의 /config 설정은 별개이며, 데스크톱 주간 한도 카드에는 같은 체크박스가 없습니다.

Server is temporarily limiting requests (not your usage limit)는 구독 할당량과 무관한 짧은 서버 제한입니다. v2.1.199부터 자동 백오프 재시도 후 표시되며, 잠시 기다리고 지속되면 상태를 확인합니다.

Request rejected (429)는 /status로 활성 인증과 연결 경로를 확인한 뒤 제공자 콘솔의 한도를 봅니다. 승인된 ANTHROPIC_API_KEY가 환경에 있으면 구독 대신 해당 키로 연결될 수 있습니다. 키 값이나 환경 변수 전체를 공개하지 말고 현재 의도한 경로인지 확인하세요. 이는 요청 제한·청구 경로 점검이지 확인된 내부 500을 인증 실패로 바꾸어 진단하는 단계가 아닙니다. 어느 자격 증명으로 과금되는지는 Claude Code API 키와 구독 결제: 어떤 경로를 써야 할까에서 비교합니다.

직접 Anthropic API의 429 설명은 속도 제한뿐 아니라 사용 등급의 월 지출 상한과 Claude Code 워크스페이스 지출 한도도 포함합니다. 사용 등급 지출 상한에 따른 429에는 retry-after가 없고 접근이 복구될 때까지 실패합니다. 헤더 하나가 없다는 사실만으로 확정하지 말고 본문과 콘솔 기록을 함께 확인하세요. 복구 후 사용량이 유난히 빠르게 줄어드는 이유를 조사하려면 컨텍스트·캐시·MCP 사용량을 대조하는 방법으로 이어갈 수 있습니다.

반복 실패할 때 지원에 남길 정보

공개 장애가 없고 같은 제공자·모델에서 안전한 재시도도 실패하면 공식 오류 보고 안내에 따라 /feedback을 사용합니다. 해당 환경에서 제공되지 않으면 문서의 다른 문의 경로를 따르세요. 게이트웨이 경로라면 운영자에게 해당 요청의 실제 제공자 응답도 확인해 달라고 요청합니다.

다음 정보는 비밀 값을 가리고 보존합니다.

• 오류 전체, 발생 시각과 시간대, claude --version 결과.
• /status의 활성 인증·제공자, 모델과 전환 여부.
• 자동·수동 재시도 결과, 부분 응답과 완료한 도구 작업 여부.
• 로그인 단계였다면 터미널과 브라우저에 표시된 문구, WSL2·SSH·컨테이너 사용 여부.
• 특정 대화만 실패했다면 그 세션 ID와 새 세션 대조 결과, 실제 복구 실패 문구.
• 가능한 요청 ID, 외부 실행 ID, 확인한 파일 및 남은 작업.

직접 API의 요청 ID는 오류 본문의 request_id와 응답 헤더의 request-id에서 받을 수 있습니다. 웹이나 게이트웨이에 Anthropic ID가 표시되지 않으면 존재하지 않는 값을 만들어 넣지 마세요. 완료 여부가 불명확한 외부 작업은 조사 중에도 다시 쓰기를 보류합니다. Claude Code가 아니라 코드에서 API를 직접 호출하다 500 api_error를 받았다면 Claude API 500 api_error 해결: 재시도 설정과 요청 ID 확인이 해당 절차입니다.

자주 묻는 질문

Claude Code API Error 500은 왜 발생하나요?

응답한 API 안에서 예상하지 못한 실패가 일어났다는 뜻입니다. 공식 오류 문서는 API 자체가 돌려준 500이 프롬프트, 설정, 계정 때문이 아니라고 설명합니다. 사용자 지정 게이트웨이를 거친다면 그 게이트웨이의 응답일 수 있고, 로그인 단계나 재개한 특정 대화에서만 반복된다면 앞의 해당 절차를 따릅니다.

500이 나오면 Claude Code를 다시 설치하거나 다시 로그인해야 하나요?

작업 중에 나온 500이라면 첫 조치가 아닙니다. 상태 페이지 확인, 1분 대기 후 한 번 재시도, 완료한 작업 대조가 먼저입니다. 다시 로그인하는 것은 /login 도중에 OAuth error: Request failed with status code 500이 나왔고 진행 중인 장애가 없을 때입니다. 이때도 /logout이 MCP 로그인과 플러그인 비밀 값까지 지운다는 점을 감안하세요.

529가 나오면 요금제를 올려야 하나요?

첫 조치는 아닙니다. Claude Code 공식 문서는 반복 529를 일시적인 API 용량 부족으로 설명하며 개인 사용 한도와 구분합니다. 먼저 제공자의 상태와 완료한 작업을 확인하고, 몇 분 대기하거나 적합한 다른 모델을 선택하세요.

생각하기가 끝났다면 자동 재시도하지 않나요?

텍스트나 도구 호출이 아직 시작되지 않았다면 예외가 있습니다. 자동 재시도 안내에 따르면 v2.1.284부터 이 시점의 서버 오류·과부하에는 최대 두 번 재시도합니다. 텍스트·도구 블록이 시작되거나 완료된 뒤의 중단은 완료한 결과를 보존하고 이어가는 절차로 구분합니다.

세션을 다시 열면 모든 작업이 원상태로 돌아오나요?

아닙니다. 세션 다시 열기, 코드 복원, 외부 작업 취소는 서로 다른 동작입니다. 먼저 올바른 대화가 열렸는지 확인하고 파일·프로세스·외부 기록을 대조하세요. 배포나 메시지 전송이 이미 끝났다면 대화를 다시 여는 것만으로 취소되지 않습니다.

선택기에 세션이 없으면 기록을 잃은 건가요?

그 사실만으로는 알 수 없습니다. 현재 복구 안내에 따르면 Ctrl+A로 모든 프로젝트를 볼 수 있으며 -p·Agent SDK 세션은 선택기에 나오지 않으므로 출력의 session_id로 지정해야 합니다. 다른 컴퓨터나 삭제된 기록일 가능성도 함께 확인합니다.

상태 페이지는 정상인데 계속 500 에러가 나면요?

정상 표시만으로 개별 요청이나 저장된 대화가 복구됐다고 볼 수 없습니다. 새 세션에서 짧은 질문을 보내 비교해 보세요. 새 세션도 실패하면 요청 경로 문제이므로 제공자·게이트웨이 상태와 /feedback으로 넘어가고, 새 세션만 정상이면 확인된 완료 상태와 남은 단계를 정리해 새 세션에서 이어갑니다. 어느 쪽이든 전체 작업을 무작정 다시 실행하지는 않습니다.