Claude 내부 서버 오류 해결: 자동 재시도와 부분 응답부터 확인하세요

Claude에서 내부 서버 오류가 나면 현재 상태, 오류가 난 화면, 이미 진행된 작업부터 확인하세요. Claude Status에 사용 중인 서비스의 장애가 올라와 있으면 복구 안내를 기다립니다. “자동으로 재시도 중…”이라면 같은 메시지를 다시 보내지 말고 자동 처리가 끝나는지 봅니다. Claude Code에 답변이나 도구 실행이 남아 있다면 원래 요청을 반복하기 전에 그 결과를 확인해야 합니다.

자동 처리가 끝났고 반복해도 안전한 작업이라면 잠시 기다린 뒤 같은 요청을 한 번 더 보낼 수 있습니다. 여기서 수동 한 번은 불필요한 반복을 막기 위한 이 글의 권장 기준입니다. 다시 실패하면 설정을 계속 바꾸기보다 오류 메시지, 발생 시각, 제공자와 요청 ID를 모아 문의하세요. 완료된 작업이 있다면 처음부터 재실행하는 대신 그 지점에서 이어가는 편이 안전합니다.

이 절차는 웹 대화, Claude Code, 직접 API, 중간 서비스를 거치는 앱을 구분합니다. 브라우저에 보이는 일반 오류와 API가 실제로 반환한 500 api_error는 같은 근거로 진단할 수 없습니다.

오류가 난 화면에 맞는 첫 조치를 고르세요

먼저 보내지 못한 메시지를 복사해 두고, 오류 전체와 발생 시각을 저장합니다. Claude Code에서 작업 중이었다면 터미널에 남은 응답과 도구 결과도 보존하세요. 오류를 없애려고 대화나 설정을 삭제하면 복구에 필요한 단서를 잃을 수 있습니다.

상태가 정상으로 보인다는 이유만으로 내 컴퓨터가 원인이라고 판단하지 마세요. 반대로 Claude라는 이름이 보인다는 이유만으로 모든 실패가 Anthropic 직접 API에서 발생했다고 판단해서도 안 됩니다.

“자동으로 재시도 중…”일 때는 기다려야 하나요?

자동 재시도가 진행 중이면 우선 기다립니다. 새로 보내기나 여러 창에서 같은 작업 실행을 겹치면 기존 재시도에 요청이 추가됩니다. 마지막 오류가 표시된 뒤에야 잠시 더 기다릴지, 완료한 작업을 확인할지, 수동으로 다시 보낼지를 결정하세요.

Claude Code의 현재 자동 재시도 문서는 일시적 실패를 지수 백오프로 최대 10회 재시도한다고 설명합니다. 이는 최초 요청까지 합친 총 10회라는 뜻이 아닙니다. 실패 시점과 오류 종류에 따라 적용되는 횟수는 다르며, 최종 오류가 보일 때는 그 실패에 해당하는 자동 재시도가 이미 이루어진 상태입니다. 화면의 횟수와 대기 표시를 확인하고 수동 재전송을 보태지 마세요.

직접 API의 공식 SDK는 별도 규칙을 씁니다. API 오류 문서에 따르면 일시적 실패를 기본 두 번 재시도하며, 설정으로 횟수를 바꿀 수 있습니다. 앱이나 게이트웨이가 별도로 재시도하면 그 기록도 확인해야 합니다. Claude Code의 10회와 SDK의 두 번을 모든 앱에 일괄 적용하거나, 서로 다른 경로의 횟수를 단순 곱셈으로 계산하면 실제 전송량과 어긋날 수 있습니다.

최종 표시가 반복 529 과부하라면 Claude Code 공식 안내는 몇 분 기다린 뒤 다시 시도하고 사용 중인 제공자의 상태를 확인하도록 권합니다. 다른 모델이 실제로 제공되고 작업에도 적합하다면 /model 또는 앱의 모델 선택기로 바꾸는 방법도 있습니다. 모델 변경은 임시 선택이며, 원래 모델이 복구됐다는 확인은 아닙니다.

웹의 “현재 사용량이 많다”는 메시지도 개인 사용 한도와 구분하세요. Claude 오류 도움말은 서비스 용량 부족일 때 몇 분 후 다시 시도하도록 안내합니다. 반면 사용 한도에 도달했다는 메시지는 다시 이용할 수 있는 시각을 표시합니다. 용량 부족 문구만 보고 유료 플랜을 바꾸거나 API 키를 새로 만들 필요는 없습니다.

Claude 서버 상태가 정상인데도 오류가 나는 이유

공식 도움말에 따르면 용량 부족은 공개 장애와 다릅니다. 서비스가 높은 수요를 조절하는 상황이며, 이런 용량 제약은 상태 페이지에 표시되지 않습니다. 따라서 녹색 상태와 과부하 메시지가 함께 나타날 수 있습니다.

상태 페이지에서는 사용하는 구성 요소와 사고의 영향 범위, 마지막 업데이트 시각을 봅니다. Claude.ai 장애인지, Claude Code 또는 API에 영향을 주는지 확인하세요. 해결된 과거 사고는 오늘 내 요청이 실패한 원인을 증명하지 않습니다. 당시 화면을 저장했다면 확인 시각도 함께 남겨야 문의할 때 의미가 있습니다.

공개 장애가 없는데 오류가 이어지면 한 번에 조건 하나만 비교합니다.

• 기존 웹 대화만 실패한다면: 원래 대화를 보존한 채 새 대화에서 짧은 요청으로 비교할 수 있습니다. 새 대화의 성공은 기존 대화와의 차이를 보여 주지만, 모든 서버 오류의 원인이 대화 길이라는 증거는 아닙니다.
• 로그인할 때만 오류가 난다면: 공식 로그인 안내에 따라 VPN, 확장 프로그램, 캐시와 쿠키를 점검합니다. 쿠키 삭제나 로그아웃 전에 작성 중인 내용을 보존하세요.
• 특정 클라우드나 중간 서비스에서만 실패한다면: 해당 제공자의 상태와 설정을 확인합니다. Claude.ai의 상태만으로 그 서비스의 정상 여부를 알 수 없습니다.
• HTTP 상태와 본문 없이 연결만 실패한다면: 연결 환경을 먼저 조사합니다. DNS, TLS, 프록시, 방화벽, 타임아웃은 확인 후보이지 이 오류만으로 확정된 원인은 아닙니다.

로그인 안내는 로그인 오류를 위한 절차입니다. 이미 확인된 API 내부 500을 해결하려고 브라우저 쿠키를 지우거나 계정을 다시 인증하는 조치로 확대하지 마세요.

Claude Code가 실제로 연결된 제공자를 확인하세요

Claude Code의 500 메시지 끝에는 확인할 서비스가 표시됩니다. 현재 공식 서버 오류 안내에 따르면 Anthropic 직접 API, Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 또는 사용자 지정 게이트웨이 중 설정된 경로에 맞춰 상태 안내가 달라집니다. ANTHROPIC_BASE_URL을 사용하는 경우에는 게이트웨이 호스트가 표시될 수 있습니다.

이 문구와 현재 연결 설정을 함께 확인하세요. 예를 들어 Bedrock을 쓰는 터미널의 오류는 Bedrock 상태와 해당 호출 기록에서 출발합니다. Claude.ai가 잘 열리는지 확인하는 것만으로 Bedrock 경로를 검증할 수는 없습니다. 중간 프록시가 HTML 오류 페이지를 반환했다면, 현재 Claude Code는 상태 코드와 페이지 제목을 보여 줄 수 있습니다. 이것 역시 Anthropic의 JSON api_error와 구분해야 합니다.

게이트웨이 관리 권한이 없다면 앱의 오류, 시간, 모델 이름, 게이트웨이 요청 ID를 운영자에게 전달하고 실제 제공자의 상태와 요청 ID를 요청하세요. 직접 API와 비교할 수 있는 환경이라면 모델, 입력, 타임아웃을 가능한 한 같게 유지합니다. 다른 모델과 다른 입력이 성공했다는 결과만으로 게이트웨이의 장애 원인을 확정할 수는 없습니다.

부분 응답이 남았다면 재시도보다 완료한 작업 확인이 먼저입니다

Claude Code가 The response above may be incomplete를 표시하면 남은 응답부터 읽습니다. 이미 완료한 도구 호출이 있을 수 있으므로 원래 작업을 처음부터 다시 보내지 마세요. 파일 수정, 실행한 명령, 배포나 메시지 전송 등 외부 작업의 결과를 확인한 뒤, 같은 세션에서 continue로 마지막 완료 지점부터 이어갈 수 있습니다.

현재 규칙은 “스트리밍이 시작되면 무조건 재시도하지 않는다”보다 세밀합니다. 공식 응답 중 오류 안내는 다음과 같이 구분합니다.

완료한 블록은 남지만, 중단된 마지막 블록은 턴이 끝날 때 버려집니다. 화면에 문장의 끝이나 미완성 도구 호출이 없을 수 있습니다. 반대로 완료된 도구 호출은 실행되고 그 결과에서 진행될 수 있으므로, 최종 오류가 보인다고 모든 작업이 취소됐다고 판단할 수 없습니다.

실제로 파일과 외부 시스템을 확인해 “무엇이 완료됐고 무엇이 남았는지”를 정리하세요. 읽기 작업만 하다 응답이 잘린 경우와 결제·배포·메시지 전송이 포함된 경우는 재실행 위험이 다릅니다. 이어가기 요청에도 완료한 작업과 남은 작업을 명확히 적으면 중복 실행을 피하는 데 도움이 됩니다. 연결 회복과 작업 완료는 각각 확인해야 합니다.

직접 API의 500·529·429·504를 구분하세요

직접 Anthropic API에서 실제 HTTP 응답을 받았다면 현재 API 오류 문서의 상태와 error.type을 함께 봅니다. 웹의 일반 오류 문구에 이 표를 그대로 적용하지 마세요.

특히 429가 항상 기다리면 풀리는 속도 제한은 아닙니다. 공식 문서는 사용 등급의 지출 상한에 따른 429에는 retry-after가 없고, 접근이 복구될 때까지 실패한다고 설명합니다. 응답 본문과 계정의 한도 정보를 함께 봐야 하며, 헤더 하나가 없다는 사실만으로 지출 상한을 확정하지는 마세요. 대기 지침이 있는 일시적 제한과 똑같이 반복하면 해결되지 않습니다.

확인된 500 api_error는 인증 실패나 결제 오류를 뜻하지 않습니다. 401·402·403처럼 다른 코드와 메시지가 나타날 때 해당 문제로 옮겨갑니다. 스트리밍에서는 처음에 HTTP 200을 받았어도 응답 도중 오류 이벤트가 발생할 수 있으므로, 처음 상태만 기록하고 성공 처리하면 안 됩니다.

직접 API를 운영하는 독자는 Claude API 500 오류의 백오프·요청 ID·운영 대응에서 별도의 운영 절차를 확인할 수 있습니다. 이 페이지에서는 여러 사용 환경에서 다음 행동을 고르는 데 집중합니다.

다시 보내도 되는지 확인하고, 반복 실패하면 멈추세요

수동 재시도 전에 세 가지를 확인합니다. 자동 재시도가 끝났는지, 반복할 작업이 안전한지, 이미 완료된 출력이나 외부 작업이 있는지입니다. 하나라도 알 수 없다면 먼저 결과와 기록을 확인하세요.

Claude Code에서 안전하게 반복할 수 있는 요청이 최종 500으로 끝났다면 공식 절차에 따라 약 1분 기다린 뒤 다시 보낼 수 있습니다. 긴 메시지는 대화에 남아 있으므로 try again으로 다시 요청할 수도 있습니다. 다만 부분 응답 안내가 나온 경우에는 위의 이어가기 절차가 먼저입니다.

처음 수동 비교에서는 모델, 서비스 주소, 인증 경로, 입력을 그대로 두세요. 같은 오류가 또 나면 이 글의 수동 한 번 기준에 따라 중지하고 문의 자료를 모읍니다. 자동 API 운영에서는 공식 SDK 설정과 작업 특성에 맞춰 재시도 횟수·전체 대기 시간·병렬 요청의 상한을 따로 정해야 합니다. 사람이 누르는 한 번이라는 기준을 운영 시스템 전체 정책으로 그대로 옮길 필요는 없습니다.

공개 장애가 진행 중이면 공식 업데이트를 기다립니다. 지출 한도라면 한도나 접근이 복구되어야 합니다. 작업 실행 상태가 불명확하면 대상 시스템에서 결과를 확인합니다. 오류가 반복될 때도 다음 행동은 원인에 맞춰 달라집니다.

지원 문의에는 무엇을 보내야 하나요?

웹 사용자에게 API 개발자용 로그가 꼭 필요한 것은 아닙니다. Claude.ai라면 전체 오류 문구, 발생 시각과 시간대, 웹·앱 구분, 사용 모델, 문제가 난 대화와 재시도 결과를 먼저 정리하세요. 작성한 메시지나 화면 캡처에 개인정보가 있다면 가립니다.

Claude Code에서는 버전, 실제 제공자, 전체 오류와 재시도 표시, 부분 응답 여부, 완료한 도구 작업을 더합니다. 공개 장애가 없고 오류가 지속되면 공식 안내의 /feedback을 사용할 수 있습니다. 환경에서 제공되지 않으면 같은 문서의 오류 보고 안내를 따르세요.

직접 API라면 다음 정보를 추가합니다.

• HTTP 상태, error.type, 오류 메시지.
• 본문의 request_id와 응답 헤더의 request-id.
• 정확한 모델 ID, SDK와 버전, 스트리밍 여부.
• 자동·수동 재시도 기록과 각 시각.
• 민감 정보를 제거한 최소 재현, 작업에 미친 영향.

API 요청 ID 안내에 따르면 직접 API 오류 본문의 request_id와 헤더의 request-id는 같은 식별자입니다. 받을 수 있는 곳에서 보존하면 지원팀이 요청을 추적하는 데 도움이 됩니다. 웹 화면이나 중간 서비스에는 Anthropic 요청 ID가 없을 수 있으므로 없는 값을 만들어 넣지 마세요.

게이트웨이가 있으면 게이트웨이 요청 ID와 실제 제공자 요청 ID를 함께 모읍니다. Anthropic 직접 호출은 Anthropic, 클라우드 경로는 해당 제공자, 모델 연결이나 프록시 처리 문제는 게이트웨이 운영자에게 추적을 요청합니다. API 키, 비공개 프롬프트 전체, 고객 데이터, 환경 변수 전체는 보내지 않습니다.

자주 묻는 질문

Claude가 지금 다운된 건가요?

오류 하나로는 알 수 없습니다. 현재 Claude Status에서 사용하는 서비스의 사고를 확인하세요. 상태가 정상이어도 공식 도움말에서 설명하는 용량 부족은 발생할 수 있습니다.

자동 재시도 중인데 새로고침해도 되나요?

같은 작업을 다시 보내기보다 자동 처리의 종료를 먼저 확인하는 편이 좋습니다. 작성 중인 내용은 별도로 보존하세요. 최종 오류가 나오면 과부하인지, 내부 서버 오류인지, 부분 응답이 남았는지에 맞춰 대기·재시도·이어가기를 선택합니다.

내부 서버 오류면 캐시나 API 키를 바꿔야 하나요?

확인된 API 500의 첫 조치는 아닙니다. 상태와 요청 ID, 자동 재시도, 작업 결과부터 확인합니다. 캐시·쿠키 점검은 로그인이나 웹 세션 문제에, 키 점검은 인증 오류처럼 해당 신호가 있을 때 적용하세요.

Claude Code에서 생각하기가 끝났다면 재시도하지 않나요?

아닙니다. 현재 공식 문서에 따르면 v2.1.284부터 생각하기만 완료되고 텍스트나 도구 호출이 시작되기 전의 서버 오류·과부하에는 최대 두 번 재시도합니다. 텍스트나 도구 블록이 완료됐거나 생각하기 뒤 시작됐다면 원래 요청을 통째로 반복하지 않고 완료한 내용에서 이어갑니다.

429와 529는 모두 서버 혼잡인가요?

아닙니다. 직접 API 문서에서 529는 일시적 과부하입니다. 429는 속도 제한뿐 아니라 특정 지출 한도에 도달한 경우도 포함하므로 오류 본문과 한도 정보를 확인해야 합니다.

안전한 재시도 한 번도 실패하면 어떻게 하나요?

반복 전송을 멈추고 시각, 오류 전체, 사용 환경, 제공자, 재시도 기록과 가능한 요청 ID를 정리합니다. Claude Code의 완료한 작업은 보존하고, 실제 실패 구간을 추적할 수 있는 지원 창구에 문의하세요. 원인을 확인하기 전에 설정을 삭제하거나 여러 조건을 한꺼번에 바꾸지 않는 것이 다음 진단에 도움이 됩니다.