AWS SDK 및 CLI 기본 재시도(Retry) 동작 변경 해부: botocore 1.44.0·14토큰 쿼터·DynamoDB 4회 제한과 legacy 프로필 함정 점검하기

일시적 오류(50ms 백오프, 14토큰 차감)와 스로틀링 오류(1,000ms 백오프, 5토큰 차감)가 500토큰 재시도 쿼터 버킷을 거쳐 DynamoDB 및 SQS 롱폴링 보호로 이어지는 흐름을 나타낸 개념 일러스트다. 실제 콘솔 화면이 아니다.

2026년 11월 10일부로 AWS가 Python(botocore 1.44.0), JavaScript v3(3.1166.0), Go v2(v1.48.0), Rust(aws-config 1.13.2), .NET(4.0.103.0), AWS CLI(2.40.0) 등 주요 AWS SDK와 도구에서 새로운 재시도(Retry) 동작을 기본값(Default)으로 전환하고 기존의 옵트인 플래그(AWS_NEW_RETRIES_2026)를 제거했다. 지난 5월 예고되었던 일시적 오류 50ms 백오프, 재시도 쿼터(Token bucket) 차감 비용 14토큰 상향, DynamoDB 최대 시도 횟수 축소(4회), 그리고 Python·Ruby·PHP·Swift의 기본 모드 전환(legacy → standard)이 이제 패키지 업그레이드 즉시 자동 적용된다. AWS Developer Tools Blog 공식 발표, 2026년 5월 초기 예고 발표문, AWS SDK 및 도구 재시도 동작 공식 문서

결론부터 말하면 이번 업데이트 이후에는 AWS_NEW_RETRIES_2026=false를 설정해도 이전 재시도 동작으로 돌아가지 않으며, 공용 ~/.aws/config에 무심코 retry_mode = legacy를 넣으면 Go·Rust 등 legacy를 지원하지 않는 다른 SDK가 프로필 전체(자격증명·리전 포함)를 무시하거나 로딩 에러를 낼 수 있다. 또한 대규모 HTTP 500 장애 시 재시도 토큰 버킷이 기존보다 약 30% 빠르게 소진(50회 → 35회)되고 DynamoDB의 기본 최대 시도가 최대 10~12회에서 4회(초기 1회 + 재시도 3회)로 줄어들기 때문에, 높은 재시도 횟수에 의존하던 배치·스트림 워크로드는 업그레이드 전에 명시적 오버라이드를 준비해야 한다.

이 글은 2026년 11월 10일 AWS 공식 발표문과 AWS SDK Reference Guide를 교차 검증해 정리한 마이그레이션 가이드다. 실제 AWS 리전 장애 상황의 네트워크 지연은 직접 측정하지 않았으며, 로컬 Python 검증 코드는 500토큰 버킷 소진 수식과 설정 우선순위·프로필 충돌 규칙만 시뮬레이션한다.

1. 무엇이 어떻게 바뀌었는가: 5대 핵심 변경 사항 비교

이번 업데이트는 standard 및 adaptive 모드의 내부 타이밍과 쿼터 계산식을 통일하고, 그동안 legacy 모드에 머물러 있던 SDK들의 기본 모드를 standard로 끌어올렸다.

변경 영역	기존 기본 동작 (2026년 11월 10일 이전)	신규 기본 동작 (2026년 11월 10일 릴리스 이후)	운영 및 아키텍처 영향
1. 기본 재시도 모드 (Python, Ruby, PHP, Swift)	`legacy` 모드가 기본값 (표준화된 재시도 쿼터가 없거나 재시도 대상 오류·횟수가 언어마다 불일치)	`standard` 모드가 기본값 (기본 최대 시도 3회, 지수 백오프 + 지터, 500토큰 재시도 쿼터 적용)	장기 장애 시 무한정에 가까운 재시도로 스레드·커넥션 풀이 고갈되던 문제가 해소되나, 애플리케이션에 예외가 더 일찍 반환됨
2. 오류 유형별 기본 백오프 지연 (Base Delay)	SDK 및 오류 유형마다 상이 (일시적 오류에도 긴 초기 대기 시간이 걸리는 경우 존재)	일시적 오류(연결 리셋, HTTP `500`/`502`/`503`/`504`)는 `50 ms`, 스로틀링 오류는 `1,000 ms` 기본 지연 사용	일시적인 네트워크 순단이나 단일 5xx 오류 발생 시 첫 재시도가 훨씬 빠르게 수행되어 P99 지연 시간 단축
3. 재시도 쿼터(Token Bucket) 차감 비용	일시적 오류 재시도 시 5토큰 또는 10토큰 차감 (초기 버킷 용량 500토큰 기준 연속 50~100회 재시도 가능)	일시적 오류 재시도 시 `14토큰` 차감, 스로틀링 재시도 시 `5토큰` 차감	연속적인 5xx 장애 발생 시 35회 재시도(`500 // 14 = 35`) 시점에 쿼터가 소진되어 빠른 실패(Fail-fast) 유도
4. Amazon DynamoDB 및 Streams 전용 튜닝	SDK마다 상이 (예: 일부 SDK의 `legacy` 모드에서는 최대 10~12회까지 시도)	기본 지연 `25 ms`, 최대 시도 `4회`(초기 1회 + 재시도 3회)로 전 SDK 통일	저지연 특성에 맞춰 초기 복구는 빨라지지만, 핫 파티션 버스트를 10회 재시도로 버티던 워크로드는 `ProvisionedThroughputExceededException` 노출이 늘어날 수 있음
5. 롱폴링(Long-polling) 및 옵트인 환경 변수	`AWS_NEW_RETRIES_2026=true/false`로 새 동작 제어 가능	`AWS_NEW_RETRIES_2026` 변수 완전 무시. 쿼터 소진 시 `SQS ReceiveMessage` 등 롱폴링 작업은 에러 반환 전 백오프 지연 적용	`AWS_NEW_RETRIES_2026=false`로 롤백할 수 없으며, 쿼터 고갈 상태의 SQS 폴러가 타이트 루프로 CPU·네트워크를 태우는 현상 방지

2. 언어·도구별 기본값 적용 시작 버전과 설정 반영 경계

Java 2.x와 Kotlin을 제외한 모든 주요 SDK와 CLI에서 아래 버전부터 새 재시도 동작이 기본값으로 활성화된다.

언어 / 도구	기본값 전환 시작 버전	현재 내 코드의 설정 상태에 따른 영향 범위
Python (Boto3 / botocore)	`botocore 1.44.0` 이상	별도 설정이 없었다면 `legacy`(기본 5회 시도, DynamoDB 10회 재시도)에서 `standard`(기본 3회 시도, DynamoDB 4회 시도, 14토큰 쿼터)로 즉시 전환됨
JavaScript v3	`3.1166.0` 이상 (`@smithy/core 3.40.0` 이상 포함)	이미 `standard`가 기본이었으나, 50ms/1,000ms 백오프 타이밍과 14토큰 쿼터 차감, DynamoDB 25ms/4회 기본값이 새로 적용됨
Go v2	`v1.48.0` 이상	`standard` 모드 내 새 타이밍·쿼터·DynamoDB 규칙 적용. 코드에서 `MaxAttempts`를 명시했다면 해당 횟수는 유지되고 나머지 새 규칙만 적용됨
Rust	`aws-config 1.13.2` 이상 (`BehaviorVersion::v2026_11_10()` 이상 지정 시)	Rust SDK는 `BehaviorVersion`으로 동작 버전을 관리하므로 `v2026_11_10()` 이상을 사용할 때 새 기본값이 활성화됨
.NET / PowerShell / C++	`AWSSDK.Core 4.0.103.0` / PowerShell `5.0.332` / C++ `1.11.926`	`standard` 및 `adaptive` 모드의 새로운 백오프 타이밍과 쿼터 계산식 기본 적용
Ruby / PHP / Swift	`aws-sdk-core 3.267.0` / PHP `3.403.3` / Swift `1.8.24`	Python과 마찬가지로 기본 모드가 `legacy`에서 `standard`로 변경됨
AWS CLI	`2.40.0` 이상	배포 스크립트 및 CI/CD의 `aws` 명령에 새 재시도 타이밍 및 쿼터 규칙 기본 적용
Java 2.x / Kotlin	추후 공지 예정 (Kotlin은 `1.9.0` 이상에서 옵트인 테스트 가능)	아직 기본값이 바뀌지 않았으므로 현행 동작 유지

3. 이전 동작 보존 방법과 공용 `~/.aws/config`에 `legacy` 설정 시 주의할 함정

업그레이드 후 특정 워크로드에서 에러율이 높아져 이전 동작으로 되돌려야 할 때 가장 조심해야 할 부분은 환경 변수나 공용 설정 파일(~/.aws/config)의 오염이다.

함정 1: AWS_NEW_RETRIES_2026=false는 아무 효과가 없다: 이번 버전부터 SDK는 AWS_NEW_RETRIES_2026 환경 변수를 아예 읽지 않는다.

함정 2: 공용 프로필에 retry_mode = legacy를 넣으면 다른 SDK가 깨진다: Python이나 Ruby에서는 AWS_RETRY_MODE=legacy가 동작하지만, legacy 모드를 지원하지 않는 일부 SDK나 도구와 같은 머신·컨테이너 환경이나 ~/.aws/config 프로필을 공유하면 설정 로드 시 에러가 발생하거나 자격증명·리전을 포함한 프로필 전체가 무시될 수 있다.

따라서 여러 언어나 CLI 도구가 공존하는 환경에서는 전역 환경 변수 대신 **애플리케이션 코드 내부의 클라이언트 설정(최우선 순위)**으로 필요한 값(max_attempts 등)만 핀포인트로 지정하는 것이 안전하다.

4. 로컬 Python으로 검증하는 14토큰 쿼터 소진 수식과 설정 충돌 진단기

연속적인 일시적 오류(HTTP 500/502/503/504) 발생 시 기존 10토큰 차감 방식과 신규 14토큰 차감 방식에서 500토큰 버킷이 몇 번째 재시도에서 고갈되는지, 그리고 환경 변수·공용 프로필 조합에서 어떤 충돌이 나는지 로컬 Python 코드로 검증했다.

직접 실행해 확인한 범위

로컬 환경에서 세 가지 경계 조건을 실행해 확인했다.

연속 60회 일시적 오류(HTTP 500) 발생 시 쿼터 소진 시점: 기존 10토큰 차감에서는 50회 재시도 후 잔여 토큰이 0이 되지만, 신규 14토큰 차감에서는 35회 재시도 후 잔여 토큰 10이 남아 36번째부터 즉시 쿼터 차단(quota_blocked: 25)이 동작한다.

연속 100회 스로틀링(HTTP 429) 발생 시 동작: 스로틀링 차감 비용은 5토큰으로 유지되므로 100회 모두 재시도가 수행된다.

폐기된 플래그 및 공용 legacy 프로필 경고: AWS_NEW_RETRIES_2026=false와 공용 legacy 모드를 함께 설정한 상태에서 go_v2 워크로드를 감사하면 dead_flag_ignored:AWS_NEW_RETRIES_2026과 profile_or_config_load_failure_on_legacy:go_v2를 정확히 검출한다.

5. 프로덕션 업그레이드 전 점검 체크리스트

Python·Ruby·PHP·Swift 워크로드의 최대 시도 횟수 확인: 기존 legacy 기본값에서 standard(최대 3회 시도, DynamoDB는 4회 시도)로 바뀌므로, 순간적인 버스트 트래픽에서 재시도 횟수에 의존하던 코드는 클라이언트 생성 시 max_attempts를 명시적으로 지정한다.