Claude 529 Overloaded 오류: 재시도 전에 확인할 것

Claude의 529 overloaded_error는 Claude API가 일시적으로 과부하 상태임을 뜻한다. 429 rate_limit_error와는 다른 오류다. 다만 화면에 529가 보였다는 사실만으로 전체 장애인지, 직접 Anthropic API가 보낸 응답인지, 이미 몇 번 재시도됐는지까지 알 수는 없다.

따라서 곧바로 다시 실행하지 말고, 먼저 아래 정보를 남긴다.

• 오류 원문과 발생 시각(시간대 포함)
• 사용한 화면: Claude Code, claude.ai, 직접 API, 클라우드 제공자 또는 서드파티 게이트웨이
• 호출한 호스트와 모델
• request-id 또는 오류 본문의 request_id
• 받은 부분 응답과 이미 실행된 도구·외부 작업
• SDK, 앱, 큐, 게이트웨이가 이미 수행한 재시도 횟수

이 기록이 있어야 재시도 폭주, 도구 중복 실행, 결과 중복, 원인 불명의 비용 문제를 피할 수 있다.

529와 429부터 구분한다

Anthropic의 공식 API 오류 문서는 두 오류를 별도로 정의한다.

529를 사용량 한도로 보고 결제 설정부터 바꾸거나, 429를 전체 서비스 과부하로 보고 무작정 기다리면 진단 경로가 어긋난다. 프록시나 게이트웨이가 오류 코드를 변환할 수도 있으므로 상태 코드뿐 아니라 응답 본문, 헤더, 호출 호스트도 함께 확인해야 한다.

어디서 오류를 봤는지가 대응을 결정한다

Claude Code에서 본 경우

Claude Code 오류 문서에 따르면 Claude Code는 재시도 가능한 일시적 오류를 지수 백오프로 최대 10회 재시도한 뒤 오류를 표시한다. 즉, 최종 529를 봤다면 이미 여러 차례 시도했을 수 있다. 바깥에서 셸 루프나 작업 큐로 다시 감싸기 전에 Claude Code 자체 재시도와 상위 자동화의 재시도 횟수를 함께 세어야 한다.

Claude Code 문서가 말하는 두 가지 경계도 중요하다.

• 반복 529는 Claude Code의 사용량 제한 오류가 아니며 Claude Code quota에 포함되지 않는다.
• 완성된 텍스트 블록이나 도구 호출 뒤 스트림이 끊긴 경우에는 같은 도구가 두 번 실행될 수 있어 중간 실패를 자동으로 다시 실행하지 않는다.

이 설명을 직접 API나 서드파티 게이트웨이의 과금 보장으로 확대하면 안 된다. 해당 경로의 사용량 기록과 계약은 별도로 확인해야 한다.

직접 Anthropic API를 호출한 경우

공식 Anthropic SDK는 연결 오류, 속도 제한, 5xx 서버 오류 같은 일시적 실패를 기본적으로 두 번 자동 재시도하고, retry-after가 있으면 이를 따른다. 언어별 SDK 버전과 max_retries 설정은 다를 수 있으므로 실제 설정을 확인한다.

애플리케이션에도 재시도 코드가 있다면 SDK 재시도와 중첩된다. 예를 들어 SDK가 한 논리 요청을 최대 3번 호출하고 앱이 그 작업을 3번 시도하면, 다른 계층이 없더라도 실제 호출은 최대 9번까지 늘 수 있다. 큐 재전달과 게이트웨이 재시도까지 더해지면 호출 수는 곱으로 커진다.

text
최대 실제 호출 수
= SDK 시도 수 × 앱 시도 수 × 큐 전달 수 × 게이트웨이 시도 수

각 숫자를 알 수 없다면 새 재시도부터 추가할 때가 아니라, 어느 한 계층이 재시도를 소유하도록 정리할 때다.

claude.ai 웹에서 본 경우

웹 화면의 529만으로 직접 API와 같은 요청 경로라고 단정할 수 없다. 먼저 Claude 상태 페이지에서 claude.ai 구성 요소를 확인하고, 오류 시각에 관련 incident가 있었는지 본다.

다시 불러오기 전에는 작성 중인 입력과 부분 결과를 복사한다. 외부 도구나 작업을 실행하지 않은 단순 대화라면 제한된 수동 재시도를 고려할 수 있지만, 캐시 삭제·재로그인·브라우저 변경을 529의 보편적 해결책으로 취급할 근거는 없다. 그런 조치는 인증이나 로컬 UI 문제의 별도 징후가 있을 때만 판단한다.

클라우드 제공자나 서드파티 게이트웨이에서 본 경우

게이트웨이가 반환한 529를 Anthropic 원본 529로 간주하지 않는다. 다음을 먼저 찾는다.

• 실제 호출 호스트와 provider 이름
• 게이트웨이 request ID와 가능한 upstream request ID
• 오류를 전달했는지 자체 코드로 변환했는지
• 게이트웨이의 자동 재시도, failover, timeout 정책
• 게이트웨이와 upstream 양쪽의 사용량·비용 기록

상태 페이지도 실제 provider의 것을 확인해야 한다. Anthropic 상태가 정상이어도 중간 경로에서만 실패할 수 있고, 반대로 집계 상태가 정상이더라도 특정 모델·리전·계정·짧은 시간대의 실패를 배제하지는 못한다.

안전한 복구 순서

1. 현재 작업을 보존한다

오류 창을 닫기 전에 원문, 시각, 모델, 요청 식별자, 부분 출력을 저장한다. 코드 수정, 파일 쓰기, 결제, 메시지 발송처럼 외부 상태를 바꾸는 도구가 호출됐다면 실제 완료 여부를 먼저 확인한다. 완료 여부가 불명확한 작업은 같은 입력을 그대로 재실행하지 않는다.

스트리밍 API는 최초 HTTP 응답이 200이어도 이후 SSE 스트림에서 오류가 날 수 있다. 따라서 200을 받음과 응답을 끝까지 완료함을 같은 상태로 기록하면 안 된다.

2. 상태 페이지를 구성 요소별로 본다

All Systems Operational 한 줄만 보지 말고 자신이 쓰는 Claude API, Claude Code, claude.ai 등의 구성 요소와 incident 시간을 확인한다. 상태 페이지는 전체 경향을 알려 주지만 개별 요청의 원인을 증명하지 않는다.

3. 재시도 소유자를 한 곳으로 정한다

SDK, Claude Code, 애플리케이션, 큐, 게이트웨이 가운데 누가 재시도를 수행하는지 표로 적는다.

가능하면 한 계층만 재시도를 소유하게 한다. 여러 계층이 필요하다면 전체 호출 상한과 전체 시간 예산을 먼저 정한다.

4. 재시도 가능한 요청만 제한적으로 다시 보낸다

다음 조건을 모두 확인했을 때만 제한된 재시도를 고려한다.

• 오류가 일시적 실패로 분류된다.
• 이미 수행된 재시도 횟수를 안다.
• retry-after가 있으면 따른다.
• 지수 백오프와 무작위 지연(jitter)을 사용한다.
• 최대 시도 수 또는 전체 시간 예산이 있다.
• 중복 실행 시 피해가 있는 작업은 완료 여부를 조회하거나 멱등성을 확보했다.

짧은 간격의 동시 재전송은 서버가 회복할 시간을 주지 못하고 자신의 큐만 키울 수 있다. 반복 529가 계속되면 새 호출 유입을 잠시 줄이고, 큐를 보존한 채 circuit breaker나 운영자 중단 조건을 적용하는 편이 안전하다.

5. 멈추거나 우회할 조건을 정한다

아래 중 하나면 자동 재시도를 중단한다.

• 정한 시도 수나 시간 예산을 소진했다.
• 도구 호출 또는 외부 부작용의 완료 여부가 불명확하다.
• request ID, 응답 본문, provider를 확보하지 못해 호출 경로를 구분할 수 없다.
• 재시도할수록 오류율이나 큐 적체가 커진다.
• 비용·사용량 기록이 예상과 맞지 않는다.

Claude Code에서는 문서상 모델별로 capacity가 추적되므로, 경로가 허용하고 작업 품질 요건을 만족할 때 다른 모델을 선택하는 것이 한 가지 우회가 될 수 있다. 하지만 모델 전환은 가용성, 정책, 기능 차이를 확인한 뒤 해야 하며 복구를 보장하지 않는다.

무인 재시도 옵션은 기본 해결책이 아니다

Claude Code의 CLAUDE_CODE_RETRY_WATCHDOG=1은 무인 세션에서 429와 529 capacity 오류를 무기한 재시도하고, 다른 일시적 오류의 기본 재시도 횟수를 300회로 높이는 옵션이다. 오래 기다리는 작업에는 유용할 수 있지만, 단순히 529를 없애는 스위치는 아니다.

활성화하기 전에 최소한 다음을 갖춰야 한다.

• 작업별 동시성 제한
• 비용·시간 예산과 강제 종료 조건
• 도구 호출의 멱등성 또는 중복 감지
• 큐 적체와 실패율 모니터링
• 부분 완료 작업을 재개할 수 있는 체크포인트

이 장치가 없다면 무제한 재시도가 장애를 더 큰 운영 문제로 바꿀 수 있다.

지원 문의에 포함할 정보

제한된 재시도 후에도 실패하거나 비용·중복 실행이 의심되면 다음 묶음으로 문의한다.

text
발생 시각과 시간대:
사용 surface / client version:
provider / 호출 호스트:
모델:
HTTP 상태와 오류 type/message:
Anthropic request-id / gateway request ID:
retry-after:
SDK·앱·큐·게이트웨이별 시도 횟수:
스트림 시작 여부와 마지막 정상 이벤트:
부분 결과 또는 도구 부작용:
관련 usage·비용 기록:
오류 시각의 상태 페이지 구성 요소:

API 키, 인증 토큰, 민감한 프롬프트, 개인정보는 제거한다. request ID는 요청을 추적하는 단서이지 완료·과금·멱등성을 단독으로 증명하는 자료는 아니다.

자주 묻는 질문

몇 분 기다리면 해결되나요?

보편적인 복구 시간은 없다. 상태 페이지와 해당 구성 요소의 incident, retry-after, 자신의 시간 예산을 기준으로 판단한다. 고정된 5분 또는 10분을 성공 공식으로 보면 안 된다.

529가 나면 비용이 청구되지 않나요?

직접 API, timeout, 스트림 중간 실패, 게이트웨이 경로 전체에 적용되는 무과금 보장은 공식 오류 설명만으로 확인할 수 없다. request ID와 provider·gateway 사용량 기록을 대조해야 한다. Claude Code의 quota 설명을 직접 API 비용에 적용하지 않는다.

상태 페이지가 정상인데 왜 529가 나오나요?

집계 상태는 짧은 장애나 특정 모델, 리전, 계정, 요청 경로의 문제를 놓칠 수 있다. 게이트웨이 자체 오류일 수도 있다. 오류 시각과 호출 경로를 기준으로 로그를 맞춰 보는 것이 필요하다.

그냥 같은 명령을 다시 실행해도 되나요?

읽기 전용 요청이고 부분 결과나 외부 부작용이 없으며 기존 재시도 횟수를 알고 있을 때만 제한적으로 고려한다. 파일 수정, 도구 호출, 결제, 발송처럼 중복 피해가 가능한 작업이라면 완료 여부를 먼저 확인한다.

529에서 가장 중요한 것은 더 빨리 다시 누르는 일이 아니다. 어느 경로가 실패했고, 누가 이미 재시도했으며, 이전 시도가 무엇을 남겼는지 확인한 뒤 한정된 복구를 선택하는 것이다. 이 세 가지를 기록하면 일시적 과부하를 재시도 폭주나 중복 작업으로 키우지 않고, 필요한 경우 근거를 갖춰 지원으로 넘길 수 있다.