개요
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 키에서 기본 조직을 사용하는 경우 기본 조직 설정을 확인하세요. 조직마다 결제 방식과 사용량 등급이 다를 수 있습니다.
일시적인 요청 한도 오류 줄이기
요청 속도 조절 및 요청 집중 방지
많은 요청을 한꺼번에 보내지 말고 시간 간격을 두고 분산하세요.
요청 한도는 표시된 간격보다 짧은 기간을 기준으로 적용될 수 있습니다. 예를 들어 분당 요청 60건의 한도가 1초 단위로도 적용될 수 있습니다. 따라서 평균 사용량이 분당 한도보다 적어 보여도 요청이 짧은 시간에 몰리면 오류가 발생할 수 있습니다.
긴 프롬프트와 필요 이상으로 큰 출력 토큰 허용량도 토큰 요청 한도 오류의 원인이 될 수 있습니다.
시간을 두고 다시 시도하기
일시적인 요청 한도 오류가 발생한 경우:
응답에 Retry-After 헤더가 있는지 확인하세요.
헤더에 유효한 대기 시간이 포함되어 있다면 최소한 그만큼 기다린 후 다시 시도하세요.
헤더가 없거나 유효하지 않다면 지터를 적용한 지수 백오프를 사용하세요. 시도가 실패할 때마다 대기 시간을 늘리고 짧은 무작위 지연 시간을 추가합니다.
재시도 횟수와 재시도에 소요되는 총시간을 모두 제한하세요.
OpenAI 공식 SDK는 재시도할 수 있는 요청 한도 오류를 자동으로 다시 시도하며, Retry-After가 있으면 이를 따릅니다. 별도의 재시도 루프를 추가하기 전에 이러한 재시도를 고려하세요.
실패한 요청도 분당 한도에 반영됩니다. 같은 요청을 계속 다시 보내면 문제가 더 오래 지속될 수 있습니다.
구현 지침과 예시는 API 요청 한도 가이드를 참조하세요. 서드 파티 재시도 라이브러리는 애플리케이션에 사용하기 전에 검토하세요.
프롬프트 및 출력 크기 검토
프롬프트에서 불필요한 지침, 반복되는 맥락 및 예시를 삭제하세요. 수정한 프롬프트를 테스트하여 필요한 결과가 계속 생성되는지 확인하세요.
엔드포인트와 모델에서 지원하는 출력 토큰 매개변수를 사용하세요.
Chat Completions는 max_completion_tokens를 사용합니다.
Responses는 max_output_tokens를 사용합니다.
요청에 필요한 수준보다 허용량을 훨씬 크게 설정하지 마세요. 이러한 매개변수에는 표시되는 출력뿐 아니라 추론 토큰도 포함되므로 추론 모델을 사용할 때는 두 가지를 모두 고려하세요.
사용량 등급 검토
요청 집중을 줄이고 토큰 사용량을 검토한 후에도 오류가 계속되면 한도 페이지에서 한도를 늘릴 수 있는 방법을 확인하세요.
API 지출액이 증가하면 OpenAI에서 조직의 사용량 등급을 자동으로 상향할 수 있습니다. 일반적으로 대부분의 모델에서 요청 한도가 늘어납니다.
승인된 월별 사용량 한도는 요청 수 및 토큰 수의 요청 한도와 별개입니다. 한쪽이 늘어났다고 해서 다른 쪽도 변경되었다고 간주해서는 안 됩니다.
문제가 계속되는 경우
문제를 에스컬레이션하기 전에
정확한 오류 메시지, 오류 코드, 관련 요청 ID, 시간대가 포함된 오류 발생 시각, 계정에 표시된 관련 한도를 준비해 두세요. 이미 시도한 단계를 기록하세요.
OpenAI 지원팀에 문의
보고된 한도를 확인한 후에도 문제를 해결할 수 없다면 도움말 센터를 통해 OpenAI 지원팀에 문의하세요. API 키나 기타 인증 비밀 정보는 포함하지 마세요.