OpenAI API 429 오류, 재시도 횟수부터 늘리지 마세요

OpenAI API 오류와 재시도 설정을 설명하는 AI 생성 이미지.

OpenAI API가 429 오류로 멈췄다면, 재시도 횟수부터 늘리지 마세요. 오류 메시지와 SDK 설정 두 곳을 먼저 보면 불필요한 요청을 줄일 수 있어요.

Python으로 AI 자동화를 만드는 분을 위한 점검 순서입니다. 공식 문서를 바탕으로 설명하며, 실제 계정의 오류나 결제 내역을 재현한 사용기는 아닙니다.

429 뒤에 적힌 설명을 읽어보세요

같은 429라도 원인이 다릅니다. 요청을 너무 빨리 보냈다는 메시지라면 호출 간격을 벌려야 해요. 유효한 Retry-After가 있으면 최소 그 시간만큼 기다린 뒤 다시 시도하세요. 설치된 SDK가 긴 대기를 처리하지 못하면 바로 반복하지 말고 요청을 미루세요.

반면 credit_balance_exhausted는 선불 크레딧 소진을 뜻합니다. organization_usage_limit_exceeded는 조직에 적용된 사용 한도에 도달했다는 뜻이고요. 이런 한도 문제는 반복해서 보내도 해결되지 않습니다. 오류에 표시된 조직·프로젝트의 크레딧과 한도를 먼저 확인하세요.

로그를 다른 사람에게 보여줄 때는 API 키와 개인정보를 가리고, 상태 코드와 오류 설명만 남겨 주세요.

기본 재시도 2번은 총 2번이 아니에요

공식 Python SDK는 일부 오류에서 기본으로 두 번 더 시도합니다. 최초 요청까지 합치면 최대 세 번이에요. 연결 오류, 408·409·429, 500 이상 오류가 대상이며 요청 본문을 안전하게 다시 보낼 수 있어야 합니다.

그래서 앱 코드에는 호출이 한 줄인데 요청 기록이 여러 번 남을 수 있습니다. 재시도를 끄고 원래 오류부터 확인하려면 max_retries=0을 설정할 수 있어요.

from openai import OpenAI

client = OpenAI(max_retries=0)
# 이 client로 기존 API 호출을 수행합니다.

위 코드는 옵션을 보여주는 예시입니다. 실행 가능한 API 호출 전체가 아니며, 오류 자체를 고치는 설정도 아닙니다. 이미 client를 만들고 있다면 새 코드를 무조건 덧붙이기보다 기존 생성 부분을 확인하세요.

앱의 반복문까지 겹쳤는지 보세요

SDK는 세 번까지 시도하고, 바깥 코드도 실패할 때마다 세 번 호출한다고 가정해 볼게요. 매번 재시도 가능한 오류로 끝난다면 최대 아홉 번까지 전송을 시도할 수 있습니다. 실제 사용 기록이 아닌 횟수 계산 예시예요.

먼저 SDK 재시도와 앱 재시도를 나란히 적어보세요. 한쪽만 보고 횟수를 늘리면 기다리는 시간도 길어집니다. SDK 문서의 기본 제한시간 10분도 함수 전체가 반드시 10분 안에 끝난다는 뜻으로 읽으면 안 됩니다. 타임아웃 뒤 재시도가 이어질 수 있거든요.

결과가 불확실한 요청은 이전 작업이 처리됐는지도 확인해야 합니다. 외부 저장·메일 발송 같은 후속 작업까지 무조건 다시 실행하지 않도록 앱의 중복 처리 방지도 함께 살펴보세요.

오늘은 두 줄만 확인해 보세요

에러 로그의 상세 메시지 한 줄, client를 만드는 설정 한 줄을 나란히 놓아보세요. 속도 제한인지 한도 문제인지 구분한 다음, max_retries와 바깥 반복문을 점검하면 됩니다.

확인 기준: 2026년 10월 9일. SDK 버전에 따라 동작이 달라질 수 있으니 설치된 버전과 공식 Python SDK의 재시도 안내를 함께 확인하세요. 오류별 의미는 OpenAI 공식 오류 코드 문서에 정리되어 있습니다.