개요
API 사용에는 요청 한도가 적용됩니다. 이 한도는 일정 기간 동안의 요청 수, 토큰 수 또는 기타 사용량을 제한합니다.
429 응답은 일시적인 요청 한도 초과, 선불 잔액 소진, 지출 한도 또는 사용량 한도 도달을 나타낼 수 있습니다. 재시도하거나 결제 설정을 변경하기 전에 오류 세부 정보를 확인하세요.
원인 파악하기
오류 메시지를 읽고, error.code가 제공되었다면 함께 확인하세요. 결제 관련 오류에도 더 포괄적인 error.type 값인 insufficient_quota가 사용될 수 있습니다.
| 오류 또는 코드 | 의미 | 조치 방법 |
| 요청 수 또는 토큰 수에 대한 요청 한도 도달 | 요청이 적용되는 요청 한도를 초과하고 있습니다. | 요청 전송 속도를 조절하고 아래 재시도 지침을 따르세요. |
| credit_balance_exhausted | 조직에 남아 있는 선불 크레딧이 없습니다. | API 결제 설정에서 크레딧을 추가하세요. |
| organization_usage_limit_exceeded | 조직이 OpenAI에서 지정한 사용량 한도에 도달했습니다. | 승인된 사용량 한도의 상향을 요청하세요. |
| organization_spend_limit_exceeded | 조직이 강제 적용되는 지출 한도에 도달했습니다. | 한도를 높이거나 해제하세요. 또는 다음 월별 초기화까지 기다리세요. |
| project_spend_limit_exceeded | 프로젝트가 강제 적용되는 지출 한도에 도달했습니다. | 프로젝트 한도를 높이거나 해제하세요. 또는 다음 월별 초기화까지 기다리세요. |
결제, 지출 또는 할당량 오류가 발생한 경우 재시도해도 액세스가 복구되지 않습니다. 먼저 오류에 표시된 잔액 또는 한도 문제를 해결하세요. 강제 적용되는 지출 한도의 변경 사항이 반영되기까지 시간이 걸릴 수 있습니다.
지출 한도를 변경하려면 해당 조직 또는 프로젝트의 설정을 관리할 권한이 필요합니다. 액세스 권한이 없다면 해당 설정을 관리하는 담당자에게 요청하세요.
선불 크레딧 구매에 대해서는 선불 API 결제 설정 및 관리를 참조하세요.
여러 지출 관리 기능에 대해서는 API 지출 한도 가이드를 참조하세요.
적용되는 요청 한도 확인하기
조직의 한도 페이지에서 현재 사용 등급과 한도를 확인하세요.
요청 한도는 조직 및 프로젝트 수준에서 적용될 수 있습니다. 사용자별로 할당되는 한도가 아닙니다. 한도는 모델에 따라서도 다르며, 일부 모델 계열은 한도를 공유합니다.
오류가 어떤 한도를 가리키는지 확인하세요. 예를 들어 분당 요청 수와 분당 토큰 수에는 별도의 한도가 적용됩니다. 한쪽 한도에 도달하더라도 다른 쪽은 아직 한도 미만일 수 있습니다.
이미지 생성 API 한도 확인하기
이미지 생성 API의 요청 한도는 모델과 사용 등급에 따라 다릅니다. 모델 페이지에서 사용하는 모델을 선택해 한도를 확인하세요.
설정 방법은 이미지 생성 개발자 가이드를 참조하세요. 사용 등급에 대한 자세한 내용은 API 요청 한도 가이드를 참조하세요.
요청에 사용되는 조직 확인하기
여러 조직에 속해 있다면 요청이 의도한 조직과 프로젝트를 사용하는지 확인하세요.
API 키가 기본 조직을 사용한다면 기본 조직 설정을 확인하세요. 조직마다 결제 방식과 사용 등급이 다를 수 있습니다.
일시적인 요청 한도 오류 줄이기
요청 속도 조절 및 집중 전송 방지하기
한 번에 많은 요청을 보내지 말고 시간 간격을 두고 분산해서 보내세요.
요청 한도는 표시된 시간 단위보다 짧은 단위로 적용될 수 있습니다. 예를 들어 분당 요청 60회 한도는 1초 단위로도 적용될 수 있습니다. 따라서 평균 사용량이 분당 한도보다 낮아 보이더라도 짧은 시간에 요청이 몰리면 오류가 발생할 수 있습니다.
긴 프롬프트나 불필요하게 큰 출력 토큰 허용량도 토큰 처리량 한도 오류의 원인이 될 수 있습니다.
잠시 기다린 후 재시도하기
일시적인 요청 한도 오류가 발생하면 다음과 같이 조치하세요.
Retry-After 응답 헤더가 있는지 확인하세요.
헤더에 유효한 대기 시간이 지정되어 있다면 최소한 그 시간만큼 기다린 후 재시도하세요.
헤더가 없거나 유효하지 않다면 지터를 적용한 지수 백오프를 사용하세요. 시도가 실패할 때마다 대기 시간을 늘리고 짧은 무작위 대기 시간을 추가하는 방식입니다.
재시도 횟수와 재시도에 소요되는 총시간을 모두 제한하세요.
공식 OpenAI SDK는 재시도 가능한 요청 한도 오류에 대해 이미 자동으로 재시도하며, Retry-After가 있으면 이를 따릅니다. 별도의 재시도 루프를 추가하기 전에 이러한 자동 재시도를 고려하세요.
실패한 요청도 분당 한도에 포함됩니다. 같은 요청을 계속 다시 보내면 문제가 더 오래 지속될 수 있습니다.
구현 방법과 예시는 API 요청 한도 가이드를 참조하세요. 서드 파티 재시도 라이브러리는 애플리케이션에 사용하기 전에 검토하세요.
프롬프트 및 출력 크기 점검하기
프롬프트에서 불필요한 지침, 반복되는 맥락 정보, 예시를 제거하세요. 수정한 프롬프트를 테스트해 필요한 결과가 여전히 나오는지 확인하세요.
사용하는 엔드포인트와 모델이 지원하는 출력 토큰 매개변수를 사용하세요.
Chat Completions는 max_completion_tokens를 사용합니다.
Responses는 max_output_tokens를 사용합니다.
요청에 필요한 것보다 훨씬 큰 허용량을 설정하지 마세요. 이 매개변수에는 표시되는 출력뿐 아니라 추론 토큰도 포함되므로, 추론 모델을 사용할 때는 둘 다 고려해 허용량을 설정하세요.
사용 등급 확인하기
요청 집중을 줄이고 토큰 사용량을 점검한 후에도 오류가 계속된다면 한도 페이지에서 한도를 높일 수 있는 방법을 확인하세요.
조직의 누적 크레딧 구매액이 Build, Launch, Grow 등급의 기준 금액에 도달하면 유료 사용 등급이 자동으로 올라갑니다. 일반적으로 등급이 높을수록 요청 한도도 높아집니다. 등급별 요건은 API 요청 한도 가이드를 참조하세요.
승인된 월간 사용량 한도는 요청 수 및 토큰 수에 대한 요청 한도와 별개입니다. 한쪽 한도가 늘어났다고 해서 다른 쪽 한도도 변경되었다고 판단해서는 안 됩니다.
문제가 계속되는 경우
지원 요청 전 준비 사항
정확한 오류 메시지, 오류 코드(있는 경우), 관련 요청 ID, 시간대를 포함한 오류 발생 시각, 계정에 표시된 관련 한도를 준비해 두세요. 이미 시도한 조치도 기록해 두세요.
OpenAI 지원팀에 문의하기
오류에 표시된 한도를 확인한 후에도 문제를 해결할 수 없다면 도움말 센터를 통해 OpenAI 지원팀에 문의하세요. API 키나 기타 인증 비밀 정보는 포함하지 마세요.