Anthropic Python SDK 2.6, 제한과 키 검증 오류 구분

429 오류 안에서도 원인을 구분합니다

한국시간 2026년 11월 6일 공개된 Anthropic Python SDK 2.6.0은 사용량 증가 속도 제한과 외부 키 검증 실패를 구체적인 오류 코드로 구분합니다. 공식 타입에서 ramp_limit_exceeded는 사용량이 얼마나 빠르게 늘어날 수 있는지를 제한하는 오류이며, retry-after 헤더가 안내하는 시간 이후 재시도하도록 설명합니다. 단순히 잔액이 부족하거나 하루 사용량을 모두 썼다는 의미로 바꿔 읽으면 안 됩니다.

오류 매핑 구현은 이 코드를 HTTP 429와 연결합니다. 화면에 표시할 원인과 재시도 판단을 HTTP 상태 하나에만 맡기던 서비스라면, 같은 429라도 세부 코드를 함께 기록하는 편이 원인을 구분하기 쉽습니다. 다만 SDK 업데이트만으로 호출량 조절이나 작업 대기열이 자동으로 구성되지는 않습니다.

외부 키 검증 실패와 시간 초과는 다릅니다

external_key_validation_failed는 외부 키가 Anthropic의 검증을 통과하지 못해 요청이 거부됐다는 뜻입니다. 원인이 있으면 메시지로 제공한다고 공식 타입에 적혀 있습니다. 매핑에는 검증 실패와 검증 시간 초과가 각각 HTTP 400으로 등록돼 있고, 키가 변경된 경우는 별도의 409 코드로 다뤄집니다. 모든 오류를 '키가 틀렸습니다'라고 표시하면 일시적인 검증 지연이나 설정 변경을 놓칠 수 있습니다.

운영 로그에는 상태 코드, 세부 오류 코드, 요청을 찾을 수 있는 식별자를 남기고 실제 키 값은 제외하는 것이 좋습니다. 메시지에 없는 구체적인 실패 원인을 추측해서 사용자에게 안내하지 않는 것도 중요합니다. 검증 실패를 무제한 재시도하는 대신, 응답이 가리키는 설정과 검증 상태를 확인하는 경로를 따로 둘 수 있습니다.

플랫폼 클라이언트에도 적용되는 수정

릴리스에는 Bedrock과 Vertex 클라이언트가 오류 코드·상태에 대응하는 예외 클래스를 올바르게 발생시키는 수정도 포함됩니다. 직접 API를 호출할 때만 맞춰 둔 예외 처리를 플랫폼 연동에도 그대로 적용할 수 있는지 점검할 이유입니다. 조직 구성원을 모든 세션에서 로그아웃시키는 관리 기능 지원도 들어갔지만, 오류 분류와는 별도의 변경입니다. SDK 설치만으로 기존 세션이 종료되지는 않습니다.

적용 전 비교할 항목

테스트에서는 정상 응답, 증가 속도 제한, 외부 키 검증 실패, 검증 시간 초과를 구분해 같은 작업이 어떤 상태로 끝나는지 살펴볼 수 있습니다. 재시도 대기 중인 요청을 완료로 표시하지 않는지, 예상하지 못한 코드도 일반 오류로 남는지 함께 확인하면 됩니다. 실제 서비스의 한도나 복구 시간을 측정한 결과는 아니며, 여기서 확인한 범위는 공식 릴리스와 SDK 오류 정의입니다.

출처

• 공식 릴리스 원문
• 오류 코드와 HTTP 상태 매핑
• 사용량 증가 속도 제한의 정의
• 외부 키 검증 실패의 정의