계속 재시도하면 안 돼요. OpenAI API가 429를 반환한다고 해서 “잠시만 기다리면 괜찮아진다”는 뜻은 아니에요. 일시적인 속도 제한만 기다렸다가 재시도하는 게 맞고, 할당량 소진, 결제 이상, 조직 차원의 사용 제한은 아무리 재시도해도 회복되지 않아요. 오히려 큐를 막아버리죠.
올바른 방법은 먼저 오류 메시지, error.type, 사용 가능한 error.code를 살펴 어느 유형의 429인지 판단하는 거예요. 일시적 속도 제한이라면 유효한 Retry-After가 있을 때 그 값대로 기다리고, 없으면 무작위 지터를 넣은 지수 백오프를 사용하며 최대 횟수를 정해두세요.
이 글을 읽고 알게 되는 것
- OpenAI API의 429가 최소 몇 가지 유형으로 나뉘고, 각각 어떻게 처리해야 하는지.
Retry-After, 지수 백오프, 무작위 지터가 어떤 관계이며 언제 무엇을 써야 하는지.- 공식 SDK 자동 재시도, 작업 큐, 수동 “재시도” 버튼이 겹치면 왜 429가 커지는지.
- 요청 수 병목과 token 병목의 서로 다른 해법, 그리고 스트리밍 요청 도중 오류가 났을 때의 주의점.
목차: 본문 앞에서 개념 표와 영향 요약 표를 하나씩 보여드려 용어를 통일하고, 여러분에게 해당하는 부분을 찾도록 도와드릴게요. “객관적 사실” 부분에서는 OpenAI 공식 문서가 429를 어떻게 설명하는지 정리해요. 오류 분류, 재시도 규칙, SDK 동작이 들어 있어요. “분석적 판단” 부분에서는 엔지니어링 적용을 다뤄요. 병목 유형에 맞춘 전략 조정, 큐 상태 설계, 재시도 중첩 문제 진단, 다른 게이트웨이로 이전할 때 주의할 의미 차이를 이야기합니다.

To Know: OpenAI API 429를 이해하는 데 필요한 개념
| 개념 | 간단한 설명 |
|---|---|
| HTTP 429 | “Too Many Requests” 상태 코드. OpenAI API는 이 코드로 속도 제한(rate limit)을 나타내며, 할당량이나 사용량 제한을 나타내는 데도 사용해요 |
| 속도 제한(Rate Limit) | 일정 시간 동안 보낼 수 있는 요청량의 상한. OpenAI는 요청 수와 토큰량을 각각 집계해요 |
| RPM / TPM | 분당 요청 수, 분당 토큰 수. 둘 중 하나라도 한도에 도달하면 429가 발생할 수 있어요 |
error.type / error.code |
오류 응답 본문에 있는 구조화된 필드로, 429의 구체적인 원인을 구분할 수 있어요. 상태 코드만 보는 것보다 더 신뢰할 수 있어요 |
| Retry-After | 응답 헤더 필드로, 서버가 얼마나 기다린 뒤 다시 시도하라고 권장하는지를 나타내요. 값이 유효하면 우선적으로 따라야 해요 |
| 지수 백오프(Exponential Backoff) | 실패할 때마다 대기 시간을 배수로 늘려가는 방식이에요. 예를 들어 1초, 2초, 4초처럼 늘리며 상한을 설정해요 |
| 지터(Jitter) | 백오프 시간에 무작위량을 더해서, 다수의 클라이언트가 동시에 한꺼번에 재시도하는 것을 피해요 |
| 스트리밍 출력(Streaming) | 모델이 생성하면서 동시에 내용을 반환해요. 출력이 시작된 뒤 도중에 오류가 나면 전체를 단순히 다시 재생할 수 없어요 |
| 재시도 중첩 | SDK, 비즈니스 큐, 사용자의 수동 조작이 각각 재시도하면서 실제 요청량이 몇 배로 늘어나는 현상이에요 |
영향 개요: OpenAI API 429가 역할별로 무엇을 의미하나요
| 역할 | 주요 영향 | 주목할 점 |
|---|---|---|
| 백엔드 개발자 | 재시도 로직을 잘못 작성하면 잠깐의 속도 제한이 지속적인 장애로 확대돼요 | 429 유형을 구분하고, 재시도를 한 계층에서 일괄 담당하게 해요 |
| 배치 처리 및 데이터 작업 책임자 | 대량 작업이 요청 수와 토큰이라는 두 가지 제한에 동시에 부딪히기 쉬워요 | 제출 주기, 컨텍스트 크기, 대기열 상태 설계 |
| 제품 및 프런트엔드 | 사용자가 “재시도”를 반복해서 클릭하면 새로운 429를 계속 만들어내요 | 사용자에게 다음 시도 시간을 알려주거나 계정 문제임을 설명해요 |
| 운영 및 계정 관리자 | 할당량·과금 관련 429는 코드로 스스로 복구할 수 없어요 | 계정 상태를 신속히 발견하고 처리하며, 자동 재시도에 방치하지 말아요 |
객관적 사실: OpenAI 공식 문서는 429를 어떻게 설명하나요
이 부분은 OpenAI가 공개적으로 관리하는 오류 코드 가이드, 속도 제한 가이드, 그리고 도움말 센터의 429 문제 해결 문서를 근거로 하며, 확인 날짜는 2026-11-17이에요. 이 문서들은 계속 업데이트되는 관리 문서라서, 이 글에서는 관련 내용이 언제 최초로 게시되었는지 확인할 수 없어요. 따라서 당일 뉴스로 취급하지 않고, 현재 유효한 규칙 설명으로만 다뤄요.
OpenAI API 429 오류의 다양한 원인
공식 문서의 핵심 입장은 이래요. 같은 429라도 의미가 다를 수 있으니, 오류 메시지와 error.type, 그리고 사용 가능한 error.code를 함께 봐서 판단해야 해요. 일시적인 속도 제한과 할당량·청구·조직 사용 제한은 처리 방식이 다릅니다.
전자는 “현재 윈도우 안에서 요청이 너무 빠르거나 너무 많다”는 뜻이라 시간이 지나 윈도우가 갱신되면 회복돼요. 후자는 계정 자체의 상태와 관련된 것으로, 예를 들어 할당량 소진, 결제 문제, 조직 차원의 사용 상한 같은 것이에요. 이런 문제는 시간이 지난다고 저절로 사라지지 않습니다.
| 429 유형 | 대표적인 신호 | 대기로 해결 가능한가 | 권장 조치 |
|---|---|---|---|
| 요청 수 속도 제한 | 오류 메시지가 요청 수 상한을 가리키며, 흔한 code는 rate_limit_exceeded |
대체로 가능 | Retry-After를 따르거나, 지터를 포함한 지수 백오프 사용 |
| 토큰 양 속도 제한 | 오류 메시지가 토큰 상한을 가리킴 | 대체로 가능하지만 반복 발생하기 쉬움 | 백오프와 동시에 단일 요청의 토큰 양을 줄이기 |
| 할당량/청구/조직 제한 | 오류 메시지가 할당량이나 청구를 가리키며, 흔한 code는 insufficient_quota |
불가 | 자동 재시도 중지, 담당자에게 계정 처리 통보 |
강조하고 싶은 점은 error.code의 구체적인 값은 실제 반환 내용과 공식 문서를 기준으로 삼아야 한다는 거예요. 위 표의 code는 흔한 예시일 뿐이니, 코드에서 하드코딩된 문자열만으로 판단하지 말고 오류 메시지 원문을 함께 보관해 로그로 원인을 추적할 수 있게 하세요.
요청 수와 토큰 수는 각각 제한될 수 있어요
속도 제한 가이드에 따르면 제한은 여러 차원에서 측정되는데, 가장 자주 마주치는 건 요청 수와 토큰 수이고 두 제한은 독립적으로 적용돼요. 즉, 요청 수가 한도에 한참 못 미쳤더라도 각 요청에 긴 컨텍스트가 함께 전달되면 토큰 제한에 먼저 부딪힐 수 있어요. 반대로 아주 작은 요청을 많이 보내면 요청 수 한도를 먼저 다 써버릴 수도 있고요.
OpenAI는 응답 헤더에 속도 제한 관련 정보를 제공해요. 예를 들어 남은 요청 수, 남은 토큰 수, 각각의 재설정 시간 같은 값이죠. 이런 헤더 필드를 보면 실제로 429가 발생하기 전에 내가 어느 한도에 더 가까운지 판단하는 데 도움이 돼요.

OpenAI API 429 공식 권장 재시도 방식
재시도가 적합한 일시적 속도 제한에 대해 공식 권장 사항은 두 가지로 정리할 수 있어요.
- 유효한 Retry-After가 있으면 그대로 따르세요. 서버가 주는 가장 직접적인 신호라서 클라이언트가 추측하는 것보다 더 정확해요.
- Retry-After가 없으면 무작위 지터를 적용한 지수 백오프를 사용하세요. 기다리는 시간을 실패 횟수에 따라 늘리고 여기에 무작위 값을 더해, 모든 클라이언트가 같은 순간에 한꺼번에 재시도하는 일을 막아요.
이 두 규칙의 전제는 ‘이번 429가 기다리면 해결되는 유형’이라는 거예요. 할당량이나 과금 문제라면 아무리 정교한 백오프 알고리즘도 그저 공회전일 뿐이에요.
공식 SDK의 자동 재시도 동작
OpenAI 공식 SDK는 조건에 맞는 속도 제한 오류에 대해 자동으로 재시도해요. 구체적인 동작은 클라이언트 설정에 따라 달라져요. Python SDK를 예로 들면 max_retries 파라미터로 조정할 수 있고, 0으로 설정하면 자동 재시도를 꺼요.
이 말은, 비즈니스 코드에 재시도 로직을 한 줄도 쓰지 않았더라도 요청이 이미 여러 번 재시도되었을 수 있다는 뜻이에요. 여기에 비즈니스 계층이 재시도를 한 번 더 감싸면 실제 요청 횟수는 두 값의 곱이 돼요.
스트리밍 요청 도중 오류가 발생하면 무조건 재전송할 수는 없어요
공식 문서는 또 하나, 쉽게 지나치기 쉬운 경계를 언급해요: 스트리밍 출력이 이미 시작된 뒤에 발생한 오류는 전체 요청을 다시 보내는 방식으로 일괄 처리할 수는 없어요. 사용자가 이미 일부 내용을 봤을 수 있고, 다운스트림 시스템도 일부 데이터를 이미 소비했을 수 있거든요. 그대로 다시 보내면 내용이 중복되고 앞뒤가 어긋나며, 토큰도 중복으로 소모돼요.
분석 판단: OpenAI API 429를 엔지니어링에서 어떻게 적용할까
아래 내용은 앞서 언급한 사실을 바탕으로 한 엔지니어링 관점의 판단이며, OpenAI 공식 발언은 아니에요.
바로 활용할 수 있는 OpenAI API 429 백오프 예시
아래 예시는 몇 가지 원칙을 보여줘요. SDK 자동 재시도를 끄고 비즈니스 계층에서 일괄 처리하며, 할당량 관련 오류는 즉시 던지고, Retry-After를 우선 따르며, 없을 때는 완전 지터를 적용한 지수 백오프를 사용하고, 최대 시도 횟수를 제한해요.
import random
import time
from openai import OpenAI, RateLimitError
# SDK 자동 재시도를 꺼서 아래의 사용자 정의 재시도와 중첩되지 않도록 함
client = OpenAI(max_retries=0)
# 대기로 해결되지 않는 429 유형 (실제 응답과 공식 문서를 기준으로 함)
NON_RETRYABLE_CODES = {"insufficient_quota"}
def parse_retry_after(response):
"""Retry-After 초 수를 파싱하고, 유효하지 않으면 None을 반환. HTTP 날짜 형식은 필요에 따라 추가로 파싱할 수 있음."""
if response is None:
return None
value = response.headers.get("retry-after")
try:
seconds = float(value)
return seconds if seconds >= 0 else None
except (TypeError, ValueError):
return None
def call_with_backoff(messages, model, max_attempts=5, base=1.0, cap=60.0):
for attempt in range(max_attempts):
try:
return client.chat.completions.create(model=model, messages=messages)
except RateLimitError as e:
if e.code in NON_RETRYABLE_CODES:
raise # 할당량/과금 관련 문제는 계정 처리 흐름에 맡김
if attempt == max_attempts - 1:
raise # 상한 초과로, 큐나 알림에 맡김
wait = parse_retry_after(e.response)
if wait is None:
# 완전 지터: [0, 지수 상한] 범위에서 무작위로 선택
wait = random.uniform(0, min(cap, base * 2 ** attempt))
time.sleep(wait)
예시의 max_attempts, base, cap은 모두 시작점일 뿐 권장 값은 아니에요. 계정마다 한도 등급이 다르고 작업 형태도 다르기 때문에, 모든 계정에 맞는 단일 동시성 수치나 재시도 횟수는 존재하지 않아요. 자신의 모니터링 데이터에 맞춰 조정해야 해요.
병목 유형에 맞춘 조정: 요청 수 병목과 토큰 병목은 해법이 달라요
백오프는 “이번엔 어떻게 기다릴지”만 해결할 뿐, “왜 자꾸 한계에 부딪히는지”는 해결하지 못해요. 429를 줄이려면 먼저 어느 쪽 한계에 부딪히고 있는지부터 파악해야 해요.
요청 수 병목의 핵심은 제출 간격을 벌리는 거예요. 큐 입구에서 일정한 속도로 통과시켜 주세요. 토큰 버킷을 쓰거나 고정 간격으로 발급하는 식으로요. 대량의 작업이 같은 1초 안에 몰려나오게 두면 안 돼요. 배치 작업을 시작할 때도 시간을 분산해서, 정각에 한꺼번에 트리거되지 않도록 해요.
토큰 병목의 핵심은 한 번의 요청 크기를 줄이는 거예요. 흔한 낭비로는 매 대화 턴마다 긴 시스템 프롬프트와 대화 기록을 전부 끌어오는 경우, 같은 대형 문서를 여러 요청에 반복해서 넣는 경우, 실제로는 일부만 필요한데 자료 전체를 모델에 밀어넣는 경우가 있어요. 먼저 잘라내기나 요약, 검색을 거친 뒤 제출하는 편이 재시도 횟수를 늘리는 것보다 훨씬 효과적인 경우가 많아요.

대기열 상태에서 ‘재시도 대기’와 ‘계정 차단’을 구분해야 합니다
많은 시스템은 ‘대기 중’과 ‘실패’ 두 가지 상태만 가지고 있어요. 429를 만나면 여기서 두 가지 오판이 생깁니다. 일시적인 속도 제한을 실패로 처리해서 작업을 버리는 경우, 그리고 할당량 문제를 대기 중으로 처리해서 끝없이 기다리는 경우죠.
더 합리적인 방법은 두 가지 429를 두 개의 상태로 나누고 서로 다른 정보를 보여주는 거예요:
| 대기열 상태 | 트리거 조건 | 표시해야 할 정보 | 후속 처리 |
|---|---|---|---|
| 재시도 대기 | 일시적 속도 제한 | 다음 시도 예정 시간, 시도 횟수 | 시간이 되면 자동 재시도, 상한 도달 시 실패로 전환 |
| 계정 차단 | 할당량, 과금, 조직 사용 제한 | 차단 사유(예: 할당량 부족) | 동일 계정의 후속 작업 일시 중지, 담당자에게 통지 |
| 실패 | 재시도 상한 초과 또는 기타 복구 불가능한 오류 | 오류 유형과 원본 정보 | 수동 개입 또는 비즈니스 저하 |
‘계정 차단’에는 연쇄 효과도 따라옵니다. 같은 계정 아래의 다른 작업들도 대부분 같은 429를 만나게 되는데, 이때는 전체를 일시 중지해야 하고 각 작업이 하나씩 부딪히게 두면 안 돼요.
재시도 중첩 문제 해결: SDK, 대기열, 수동 버튼
429가 재시도할수록 더 늘어난다면, 가장 먼저 할 일은 여러 계층의 재시도가 동시에 작동하고 있는지 확인하는 거예요. 대표적인 체인은 이렇습니다. SDK가 자동으로 여러 번 재시도하고, 비즈니스 대기열은 작업 실패 후 다시 여러 번 재등록하며, 프런트엔드 사용자는 오류를 보고 수동으로 ‘재시도’를 누르는 경우죠. 세 계층이 곱해지면 하나의 원본 요청이 실제로는 십여 번의 요청이 될 수 있고, 이런 요청들이 속도 제한 윈도우에 몰리면 정확히 속도 제한을 악화시킵니다.
문제를 확인할 때는 계층별로 짚어보는 게 좋아요:
- SDK 계층:
max_retries의 실제 값을 확인하세요. 기억 속 기본값에 의존하지 마세요. - 대기열 계층: 작업 실패 후 자동으로 다시 등록되는지, 재등록에 백오프가 있는지 확인하세요.
- 상호작용 계층: ‘재시도’ 버튼이 대기 동안 비활성화되는지, 다음 시도 시간을 표시하는지 확인하세요.
- 로그 계층: 각 원본 작업에 고유 ID를 부여하고, 실제로 몇 번의 요청을 보냈는지 집계하세요.
원칙은 간단합니다. 같은 체인에서 재시도를 담당하는 계층은 하나만 남기고, 나머지 계층은 상태 전달만 담당해야 합니다.
스트리밍 시나리오에서는 OpenAI API 429 복구 전략을 별도로 설계해야 해요
스트리밍 요청이 연결을 맺고 아직 아무 내용도 출력하지 않은 단계에서 429를 만나면 일반 요청처럼 처리할 수 있어요. 하지만 일단 출력이 시작된 뒤라면 “재생(replay)할지 말지”는 비즈니스 로직이 판단해야 해요. 예를 들어 사용자에게 생성이 중단되었음을 분명히 알리고 재생성을 선택하게 하거나, 이미 출력된 부분을 버리고 전체를 교체하는 방식이에요. 백그라운드에서 조용히 재생해서 화면에 중복된 두 덩어리가 나타나게 해서는 안 돼요.
다른 플랫폼으로 이전할 때 OpenAI의 429 의미를 그대로 복사하지 마세요
이 글에서 설명한 오류 분류, error.code 값, Retry-After 동작, 응답 헤더는 모두 OpenAI 공식 API의 의미 체계예요. 만약 서드파티 게이트웨이, API 중계 서비스, 또는 집계 플랫폼(예: APIYI)을 통해 모델을 호출한다면, 상대 플랫폼의 오류 코드, 속도 제한(rate limit) 기준, 재시도 권장 사항은 반드시 해당 플랫폼 자체 문서를 기준으로 별도로 확인해야 하며, OpenAI의 동작을 그대로 따르면 안 돼요. 더 안전한 방법은 접근 계층(integration layer)에서 오류 정규화 계층을 두고, 서로 다른 출처의 429를 이 글에서 말한 “대기 후 재시도 / 계정 차단 / 실패” 세 가지 상태로 매핑한 뒤 통합 재시도 모듈에 넘기는 거예요.
계속 주목해야 할 변화
OpenAI의 오류 코드 문서와 속도 제한 문서는 모두 지속적으로 관리되고 있어요. 제한 등급, 과금 기준, 응답 헤더 필드가 언제든 조정될 수 있죠. 코드 안에 오류 원문 로그를 남겨 두고, 정기적으로 공식 문서와 대조하면서 판단 로직을 다시 점검하길 권해요. 그리고 “모든 429는 기다리면 해결된다”는 생각을 어떤 기본 설정에도 넣지 마세요. 이 가정이 할당량이 바닥난 상황에서 발동하면, 대가는 밤새도록 헛돌아가는 작업 큐예요.

429는 본질적으로 서버가 “조금 천천히”라고 말하는 것이고, 때로는 “이 경로는 당장은 막혀 있다”고 말하는 것이에요. 어느 쪽인지 구분한 다음에 기다릴지, 바꿀지, 멈출지를 정하는 것이 어떤 정교한 재시도 알고리즘보다 중요하죠. 《논어·자로》에서 말한 것처럼요:
“서두르지 말고, 작은 이익을 탐하지 말라. 서두르면 도달하지 못하고, 작은 이익을 탐하면 큰일을 이루지 못한다.”
