AIMLAPI에서 429가 발생하면 애플리케이션과 SDK가 모두 재시도하는지 먼저 확인하자

AIMLAPI의 공식 Python SDK 문서는 기본값으로 두 번의 자동 재시도를 명시한다. 외부 작업 계층에서도 재시도하면 요청 횟수가 겹쳐 늘어난다. 출시 전에 재시도 책임을 일원화하고 매개변수 오류, 잔액 부족, 요청 제한을 구분해 처리해야 한다.

출처: github.com
2026년 11월 11일
6 min

여러 모델을 하나의 인터페이스로 연결하면 연동 코드는 줄일 수 있지만, 모델들의 매개변수 제약이나 장애 동작까지 같아지는 것은 아니다. AIMLAPI를 고객용 기능에 연결하려는 팀은 실패 시 시스템이 무엇을 하는지 먼저 확인할 필요가 있다. 사용자 조작 한 번에 호출이 실제로 몇 번 발생하는지, 언제 멈추는지, 실패 후 누가 처리를 맡는지 확인해야 한다. 이 글은 공식 오류 설명, 키 문서, Python SDK README를 바탕으로 이러한 경계를 분석하며, 부하 테스트는 실행하지 않았다.

두 계층의 재시도는 한 번의 실패를 증폭시킨다

공식 Python SDK README에 따르면 연결 오류, 408, 409, 429 및 500 이상의 오류는 기본적으로 두 번 자동 재시도하며, max_retries로 횟수를 조정하거나 끌 수 있다. 여기서 ‘두 번 재시도’는 최초 호출에 추가되는 횟수다. 애플리케이션의 외부 계층도 실패 후 전체 호출을 두 번 재시도하고, 매번 SDK 호출에서 재시도 가능한 오류가 발생해 기본 재시도 횟수를 모두 소진한다고 가정하면, 하나의 업무 작업에서 최대 3 × 3 = 9회의 시도가 발생할 수 있다. 이는 명시된 가정에 따라 계산한 상한 예시이며, 플랫폼에서 실측한 트래픽도 아니고 아홉 번 모두 과금된다는 뜻도 아니다.

도움말 센터는 429를 요청 속도 또는 동시 실행 제한으로 설명하며, 요청 속도 낮추기, 대기 간격을 늘리는 재시도, 대기열 사용을 권한다. 외부 계층이 실패했다는 이유만으로 즉시 다시 보내면 같은 제한을 더 심하게 만들 수 있다. 하나의 계층에서 재시도 허용 횟수를 통합 관리하고 각 시도의 이유와 횟수를 기록한 뒤, 업무 작업에 명확한 중단 조건을 설정하는 것이 좋다. 브라우저, 작업 대기열, SDK가 각각 독립적으로 무한 재전송을 결정하게 해서는 안 된다.

대기 시간도 별도로 검토해야 한다. SDK README에 명시된 기본 요청 타임아웃은 10분이며 timeout으로 설정할 수 있다. 이 기본값을 고객에게 약속하는 대기 시간으로 그대로 사용할 수는 없다. 대화형 기능에는 자체적인 총 대기 시간 한도와 명확한 시간 초과 안내가 필요하며, 백그라운드 작업에서는 사용자가 처리 중, 실패, 완료의 실제 상태를 확인할 수 있어야 한다.

재시도로 해결되지 않는 오류도 있다

공식 오류 표는 400이 발생하는 한 가지 경우로 선택한 모델이 messages의 system 역할을 지원하지 않는 상황을 제시한다. 이런 경우에는 통합 인터페이스라고 해서 모든 모델이 같은 매개변수를 받는다고 가정하지 말고, 해당 모델의 schema에 맞춰 요청을 수정해야 한다. 대체 모델로 전환하기 전에도 기존 메시지 구조와 작업 요구 사항을 수용할 수 있는지 검증해야 한다. 그렇지 않으면 서비스의 대체 운영이 또 다른 요청 오류로 바뀐다.

오류 표는 잔액이나 요금제 한도 소진도 403으로 분류한다. 이는 429와 처리 방향이 다르다. 전자는 계정 한도와 예산을 확인해야 하고, 후자는 호출 속도를 제어해야 한다. 모니터링에서 각각 따로 분류하고 민감한 내용을 포함하지 않는 요청 식별자와 오류 정보를 보관하는 것이 좋다. 성공하지 못한 모든 응답을 ‘모델 사용량이 많음’으로 묶어서도, 자동 충전으로 장애 진단을 대신해서도 안 된다.

지출 제어가 트래픽 제어를 대신할 수는 없다

키 문서에 따르면 API key마다 지출 한도를 설정할 수 있으며, 한도에 도달하면 해당 key에서 추가 비용이 발생하지 않도록 차단한다. 일별, 주별, 월별 등의 초기화 주기를 선택할 수 있고 초기화는 UTC 시간을 기준으로 한다. 문서는 key가 호출할 수 있는 엔드포인트를 제한하는 것도 허용한다. 이런 기능은 프로젝트별 용도와 지출 범위를 분리하는 데 도움이 되지만, 지출 한도는 호출 속도 설정이 아니며 중복 시도가 발생하지 않는다는 보장도 아니다.

연동 전에는 팀이 통제된 실패 상황 하나를 만들어 로그를 확인하도록 할 수 있다. 400, 403, 429를 구분하는지, 실제 시도 횟수가 허용 범위에 맞는지, 총 대기 시간이 제품 요구 사항에 맞는지, 대체 모델의 호환성을 점검했는지 확인한다. 이런 문제를 맡을 담당자가 아직 없다면 통합 인터페이스의 편리함만으로는 출시를 약속하기에 부족하다. 먼저 이 검수를 마친 뒤 호출량을 늘리자.

콘텐츠 안내:이 글은 공개 자료를 바탕으로 정리한 도구 선택 참고 자료입니다. 제품 기능, 가격 및 관련 정책은 수시로 변경될 수 있으니 최신 공식 정보를 확인해 주세요.

원문 출처:github.com