세 번의 루프를 거치면서 총 9건이 전송되었습니다. Claude의 Python SDK에 429 에러를 반환하는 Mock을 만들어 오늘 직접 계산해 보았습니다.
저는 재실행 코드를 확인하면서, 외부(Outer) 반복 횟수만으로는 로그가 부족하다고 느꼈습니다. SDK 내부에서 발생하는 재시도 횟수도 함께 세고 싶었습니다.
검증 환경은 macOS, CPython 3.12.13이며, anthropic==0.102.0과 httpx==0.28.1을 사용했습니다. 실제 API 연결 없이 MockTransport를 사용하여 매번 429 에러를 반환하도록 설정했습니다.
여기서 max_retries는 '최초 전송을 제외한 재시도 횟수'입니다. 기본값 2라면, 한 번의 messages.create() 호출로 최대 3건이 전송됩니다. 만약 모든 시도가 재시도로 처리되는 에러라면, 외부 루프 3회와 곱해져 총 9건이 됩니다.
SDK는 RateLimitError를 받으면 재시도를 사용합니다. 이 재시도 횟수를 모두 소진하면, 루프가 계속 진행될 경우 새로운 SDK 호출로 간주되어 다시 최대 3건이 실행됩니다.
저는 SDK가 전송 시 붙이는 x-stainless-retry-count 헤더를 기록했습니다. model이나 API 키는 더미(dummy)만 사용했기 때문에 인증 정보는 필요하지 않았습니다.
import httpx
from anthropic import Anthropic, RateLimitError
def probe(retries):
...
max_retries=2: 9건 / 0,1,2,0,1,2,0,1,2
max_retries=0: 3건 / 0,0,0
0,1,2가 세 번씩 반복됩니다. 예외를 포착하여 다시 호출하면, 카운터가 다시 0으로 돌아갔습니다. x-stainless-retry-count는 로그의 컬럼 이름으로는 아무래도 너무 길었습니다.
저는 SDK에 포함된 소스 코드까지 읽어보았습니다. _constants.py에는 DEFAULT_MAX_RETRIES = 2가 정의되어 있고, _base_client.py에서는 range(max_retries + 1)을 사용하여 전송합니다. 심지어 429 에러도 재시도의 대상이었습니다.
SDK 내부 대기 시간은 retry-after-ms: 1로 1밀리초로 설정했습니다. 이 버전에서는 지정된 양의 대기 시간이 60초 이하일 경우 해당 값을 사용합니다.
항상 429 에러가 발생했기 때문에 총 9건까지 진행되었습니다. 중간에 성공하거나 재시도 지연 헤더(retry-after header)로 인해 전송 건수는 달라집니다. 이번에는 Mock으로의 전송 건수를 세었습니다. 모델 실행 횟수나 과금 금액은 측정하지 않았습니다.
만약 외부에서 재시도를 관리하려면, SDK의 max_retries=0과 조합하여 대기 및 종료 처리도 외부에서 다루는 것이 좋습니다. 이 코드는 외부 대기를 생략했기 때문에, 실제 429 에러 대응을 위해서는 Retry-After 헤더 처리나 백오프(Backoff) 로직을 추가해야 합니다. 만약 단발적인 호출이라면, 외부 루프를 제거하고 SDK에 맡기는 방법도 있습니다. 게이트웨이 레벨에서도 재시도를 추가하는 구성이라면, 작업 횟수와 전송 건수를 나란히 기록한 로그가 부하 테스트의 진입점이 될 것 같습니다.