Anthropic 529 overloaded_error: 의미 및 처리 방법

API가 일시적으로 오버로드되면 Claude API는 오류 유형 529와 함께 overloaded_error를 반환합니다. Anthropic에 따르면 API가 모든 사용자 간에 높은 트래픽을 경험할 때 발생할 수 있습니다. 요청은 괜찮습니다. API가 사용 중이므로 요청을 거절했습니다. 조직에서 자체 속도 제한을 초과하면 대신 429가 표시됩니다. 응답 본문은 다른 모든 Claude API 오류와 동일한 구조를 가집니다. 즉, 최상위 type의 error, type 및 message가 포함된 error 객체, 그리고 Anthropic 지원팀에 제공할 수 있는 request_id로 구성됩니다. 자세한 내용은 Claude API 오류를 참조하세요.

529, 429 또는 지출 한도: 구분하는 방법

Claude API는 매우 다른 문제에 대해 서로 비슷해 보이는 오류를 사용합니다. 당신이 기다릴 경우 일부는 사라집니다. 하나는 다음 달까지는 사라지지 않습니다.

Response	`error.type`	`retry-after`	의미	무엇을 해야 할지
`529`	`overloaded_error`	있으면 사용합니다.	API는 전체 사용자에게 영향을 미칠 정도로 과부하 상태입니다.	몇 번 대기 후 다시 시도
`429`	`rate_limit_error`	Yes	조직에서 분당 요청 수, 입력 토큰 수 또는 출력 토큰 수 제한을 초과했거나 너무 빠르게 증가하여 가속 제한에 도달했습니다.	`retry-after`에서 안내하는 대로 기다립니다.
`429`	`rate_limit_error`, `error.details.error_code`이(가) `enforced_spend_limit_reached`(으)로 설정된 상태에서	No	조직이 사용 계층의 월별 지출 한도에 도달했습니다.	다시 시도하지 마세요. 사용량은 다음 달 첫날 00:00 UTC 또는 더 높은 계층으로 이동할 때까지 일시 중지됩니다.
`400`	`invalid_request_error`	No	사용량이 조직 또는 작업 영역에 설정한 지출 한도에 도달했습니다.	한도를 올리거나 제거

지출 한도 429는 속도 제한과 동일한 오류 유형을 가지므로 rate_limit_error마다 다시 시도하는 코드는 계속 실패합니다. Anthropic SDK의 자동 재시도를 포함하여 액세스가 재개될 때까지 재시도는 실패합니다. 자세한 내용은 지출 한도 도달을 참조하세요.

529를 처리하는 방법

다시 시도하기 전에 상태 코드를 확인하세요. 529와 429는 서로 다른 대기가 필요하고, 429 없는 retry-after는 전혀 다시 시도할 필요가 없습니다.
529는 물러서세요. 지수 백오프 및 임의 지터를 사용하여 다시 시도하고 몇 번의 시도 후에 중지합니다. 응답에 retry-after 헤더가 있으면 대신 그만큼 기다리세요.
SDK가 먼저 초기 재시도를 하도록 합니다. 공식 Anthropic SDK는 기본적으로 연결 오류, 속도 제한 및 5xx 오류를 두 번 재시도하고, 지수 백오프를 사용하며, retry-after이 있으면 이를 따릅니다. maxRetries로 개수를 변경할 수 있습니다(TypeScript에서는 max_retries). SDK가 재시도 횟수를 모두 소진하면 코드에서 오류가 발생합니다.
지출 한도에 도달하면 재시도를 중지합니다. 429 응답에 retry-after 헤더가 없으면 사용자에게 알리고 스스로에게 알립니다.
사용자에게 계속 알려줍니다. 작업을 대기열에 넣고 나중에 다시 시도하거나 일반 오류 대신 명확한 "사용 중, 1분 후에 다시 시도하세요" 메시지를 표시하세요.

Python SDK에서는 429가 anthropic.RateLimitError 발생하며 529를 포함한 500 이상의 상태에서는 anthropic.InternalServerError가 발생합니다.

import anthropic

client = anthropic.Anthropic(max_retries=4)


def summarize(text: str) -> str | None:
    try:
        message = client.messages.create(
            model="claude-sonnet-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": f"Summarize:\n\n{text}"}],
        )
    except anthropic.RateLimitError as e:
        if "retry-after" not in e.response.headers:
            # Spend cap: every retry fails until access resumes
            alert_admin(e)
            return None
        raise
    except anthropic.InternalServerError as e:
        if e.status_code == 529:
            # Overloaded after all SDK retries: queue the job for later
            queue_for_later(text)
            return None
        raise
    return next(block.text for block in message.content if block.type == "text")

앱이 529를 처리하는지 테스트하는 방법

개발하는 동안 529 오류를 보는 경우는 거의 없습니다. 모든 Claude API 사용자의 트래픽에 따라 달라지므로 트리거할 수 없습니다. 어떻게 테스트하느냐가 사용자가 하기 전에 버그를 찾을지 여부를 결정합니다.

Approach	찾은 내용	당신이 놓친 것
프로덕션을 기다리세요	실시간 오버로드	사용자가 누르기 전까지 모든 것
테스트에서 API를 모킹하거나 코딩 에이전트가 모의 개체를 작성하도록 허용	해당 오류 분기 실행 여부	Anthropic 실제 상태 코드 및 오류 본문 및 SDK의 재시도 정책입니다. 또한 모의 객체에 도달하려면 앱에 테스트 전용 스위치가 필요합니다.
실패할 때까지 실제 API를 호출하세요	실제 동작	요청 시 529 오류를 의도적으로 발생시킬 수 없으며 지출 한도에 안전하게 도달하게 할 수 없습니다.
앱의 실제 트래픽을 가로채고 요청 시 529s 및 429s를 반환합니다.	실제 URL, 실제 SDK 및 재시도 정책 및 Anthropic 고유한 오류 형식	앱에서 아무것도 변경되지 않으므로 코드가 격리된 상태로 테스트되지 않습니다. 그건 단위 테스트로 확인하세요.

앱에서 체험해 보기

Dev Proxy는 https://api.anthropic.com에 대한 앱의 요청을 가로채고 Anthropic의 오류 형식으로 오류를 반환하는 한편, 앱은 실제 URL을 계속 호출합니다. 사전 설정을 다운로드하고 다음과 같이 개발 프록시를 시작합니다.

devproxy config get anthropic-throttling
devproxy --config-file "~dataFolder/configs/anthropic-throttling/.devproxy/devproxyrc.json"

Preset	반환되는 내용
`anthropic-throttling`	임의로 4개의 429 `rate_limit_error` 응답(요청, 입력 토큰, 출력 토큰 및 가속 제한) 중 1개 또는 529 `overloaded_error`개입니다. 429에서 Dev Proxy는 `retry-after`를 설정하고 앱이 API를 너무 일찍 다시 호출하면 알려줍니다.
`anthropic-random-errors`	임의로, 요청의 50%에 대해 400, 401, 402, 403, 404, 409, 413, 429, 500, 504 및 529를 포함한 Claude API 오류 목록의 오류 중 하나

두 사전 설정 모두 지출 한도 429를 포함하지 않습니다. 해당 경우를 테스트하려면 사전 설정의 retry-after 파일에 anthropic-errors.json 헤더가 없는 응답을 추가합니다.

{
  "statusCode": 429,
  "headers": [
    { "name": "content-type", "value": "application/json" }
  ],
  "body": {
    "type": "error",
    "error": {
      "type": "rate_limit_error",
      "message": "You have reached your API usage limits.",
      "details": { "error_code": "enforced_spend_limit_reached" }
    }
  }
}

모든 요청이 실패하도록 하여 SDK의 재시도 횟수를 모두 소진했을 때 무슨 일이 발생하는지 확인하려면 --failure-rate 100로 Dev Proxy를 시작하세요. 자세한 내용은 변경 요청 실패율을 참조하세요. 개발 프록시를 설치하려면 개발 프록시 설정을 참조하세요.

다음 단계

임의 오류로 내 앱 테스트

또한, 다음을 참조하세요.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-10-05