요청 한도

OpenAI API는 사용자나 클라이언트가 일정 시간 동안 OpenAI 서비스를 이용할 수 있는 횟수를 제한합니다. 이를 요청 한도라고 합니다.

요청 한도가 필요한 이유

API에 요청 한도를 두는 것은 일반적이며, 그 이유는 다음과 같습니다.

• API의 악용이나 오용을 방지하는 데 도움이 됩니다. 예를 들어 공격자는 API에 대량의 요청을 보내 과부하를 일으키거나 서비스를 방해하려 할 수 있습니다. OpenAI는 요청 한도를 설정해 이런 행위를 막을 수 있습니다.
• 누구나 API를 공정하게 이용할 수 있도록 합니다. 한 사용자나 조직이 지나치게 많은 요청을 보내면 다른 사용자가 보낸 요청의 처리도 느려질 수 있습니다. OpenAI는 한 사용자가 보낼 수 있는 요청 수를 제한해 최대한 많은 사람이 속도 저하 없이 API를 이용할 수 있도록 합니다.
• OpenAI가 인프라의 전체 부하를 관리하는 데 도움이 됩니다. API 요청이 급증하면 서버에 부담이 커져 성능 문제가 발생할 수 있습니다. 요청 한도를 설정하면 모든 사용자에게 원활하고 일관된 서비스를 제공하는 데 도움이 됩니다.

요청 한도는 어떻게 적용되나요?

요청 한도에는 RPM(분당 요청 수), RPD(일일 요청 수), TPM(분당 토큰 수), TPD(일일 토큰 수), IPM(분당 이미지 수) 등의 지표가 사용됩니다. 일부 스트리밍 오디오 모델에는 1분 동안 처리할 수 있는 오디오 길이(분)도 적용됩니다. 어느 지표든 먼저 한도에 도달하면 요청이 제한됩니다. 예를 들어 RPM 한도가 20이고 TPM 한도가 15만이라면, 1분 동안 ChatCompletions 엔드포인트에 요청 20건을 보내는 것만으로 요청 수 한도에 도달합니다. 이때 요청 20건에 사용한 토큰이 총 100개로 15만 개에 훨씬 못 미쳐도 마찬가지입니다.

Batch API의 대기열 한도는 특정 모델의 대기열에 있는 입력 토큰의 총수를 기준으로 계산합니다. 대기 중인 배치 작업의 토큰은 대기열 한도에 포함됩니다. 배치 작업이 완료되면 해당 토큰은 더 이상 그 모델의 한도에 포함되지 않습니다.

다음 사항도 알아두세요.

• 요청 한도는 개별 사용자 단위가 아니라 조직 단위와 프로젝트 단위로 정해집니다.
• 요청 한도는 사용하는 모델에 따라 다릅니다.
• GPT-5.5처럼 긴 컨텍스트를 지원하는 모델에는 긴 컨텍스트 요청에 별도의 요청 한도가 적용됩니다. 이 한도는 개발자 콘솔에서 확인할 수 있습니다.
• OpenAI는 각 조직에 승인된 월간 사용 한도를 설정합니다. 이 한도는 조직이나 프로젝트에 직접 설정할 수 있는 지출 한도와 별개입니다.
• 일부 모델 제품군은 요청 한도를 공유합니다. 조직 한도 페이지에서 같은 ‘공유 한도’ 아래에 표시된 모델에는 하나의 요청 한도가 적용됩니다. 예를 들어 공유 TPM이 350만이면 목록에 있는 어느 모델을 호출하든 사용한 토큰이 이 350만 개 한도에 합산됩니다.
• 벡터 스토어에 데이터를 추가할 때도 벡터 스토어 ID별로 요청 한도가 적용됩니다. /vector_stores/{vector_store_id}/files와 /vector_stores/{vector_store_id}/file_batches는 벡터 스토어 하나당 분당 요청 300건의 한도를 공유합니다. 대량의 데이터를 추가할 때는 /vector_stores/{vector_store_id}/file_batches를 우선 사용하세요.

사용 등급

유료 사용 등급은 Build, Launch, Grow 세 가지입니다. 조직의 누적 크레딧 구매액이 각 등급의 기준에 도달하면 사용 등급이 자동으로 올라갑니다. 일반적으로 등급이 높을수록 각 모델의 요청 한도도 높아집니다.

표준 요청 한도

현재 사용 등급에서 모델별 한도를 보려면 설정 > 조직 > 한도로 이동해 요청 한도 항목을 확인하세요. 사용 등급을 높이려면 등급 업그레이드 버튼을 선택하세요. 이 버튼은 사용 등급 섹션에 있습니다.

표준 요청 한도는 Ultrafast 요청 한도와 다릅니다.

지출 한도

월간 API 지출을 관리하려면 조직이나 프로젝트에 지출 한도를 설정하는 방안을 고려하세요. 아래 설정은 앞서 설명한 월간 사용 한도와 별개입니다.

응답 헤더에서 요청 한도 확인하기

계정 페이지에서 요청 한도를 확인할 수 있습니다. HTTP 응답 헤더에서도 남은 요청 수와 토큰 수를 비롯해 요청 한도에 관한 주요 메타데이터를 확인할 수 있습니다.

응답에는 다음 헤더 필드가 포함될 수 있습니다.

프로젝트 단위의 토큰 한도가 적용되면 프로젝트 토큰 관련 헤더가 포함될 수 있습니다. Retry-After는 일시적인 요청 한도로 인한 429 응답이나 일시적인 모델 과부하로 인한 503 응답에 포함될 수 있습니다. 이 헤더가 있다고 해서 할당량이나 결제 문제 등 사용자 조치가 필요한 오류까지 재시도로 해결할 수 있는 것은 아닙니다.

파인튜닝 요청 한도

조직의 파인튜닝 요청 한도는 대시보드에서 확인하거나 API로 조회할 수 있습니다.

curl https://api.openai.com/v1/fine_tuning/model_limits \
  -H "Authorization: Bearer $OPENAI_API_KEY"

모델 사용 가능 여부

모델 사용 권한과 요청 한도는 별개입니다. 사용 등급의 기준을 충족해도 모든 모델에 대한 사용 권한이 주어지지는 않습니다. 문서에 나오는 모델이 Playground나 GET /v1/models 응답에 표시되지 않거나 요청에서 model_not_found 오류가 반환되면 다음 순서로 확인하세요.

1. 모델 ID와 엔드포인트를 확인하세요. 모델 문서에 나온 ID를 정확히 사용하세요. 해당 모델이 사용하려는 엔드포인트를 지원하는지 확인하고, 모델 지원 종료나 사용 가능 여부에 관한 공지도 살펴보세요.
2. 조직, 프로젝트, 인증 정보를 비교하세요. Playground에서 사용하려는 조직과 프로젝트를 선택하세요. 모델 목록 조회를 호출할 때는 실패한 요청과 동일한 API 키를 사용하세요. 해당 요청에 OpenAI-Organization 또는 OpenAI-Project 헤더가 있었다면 그 헤더도 같은 값으로 보내세요. 현재 대시보드 세션에 표시되는 모델이라도 다른 API 키로는 사용하지 못할 수 있습니다.
3. 프로젝트 제한 사항과 모델 사용 요건을 검토하세요. 프로젝트를 관리할 권한이 있는 사람에게 해당 프로젝트의 모델 사용 권한과 데이터 보존 설정을 확인해 달라고 요청하세요. 모델별 접근 요건이 있다면 따르고, 모델 문서에 순차 출시에 관한 공지가 있는지도 확인하세요. 모델이 보이지 않는다는 사실만으로는 원인을 알 수 없습니다.
4. 새로고침한 뒤 다시 확인하세요. 접근 설정을 변경한 후 모델 목록이나 Playground를 새로고침하세요. 여전히 모델을 사용할 수 없다면 지원팀에 문의할 때 모델 ID, 조직 ID, 프로젝트 ID, 요청 시각, 오류 메시지를 알려 주세요. 응답에 x-request-id 헤더가 있다면 그 값도 함께 제공하세요. API 키는 공유하지 마세요.

오류 완화

트래픽 급증과 모델 과부하에 대응하기

요청 빈도가 너무 빠르게 증가하면 API가 slow_down을 반환할 수 있고, 요청한 모델에 일시적으로 과부하가 걸리면 server_is_overloaded를 반환할 수 있습니다. 두 상황을 구분하려면 HTTP 상태와 error.code를 확인하세요.

Retry-After가 없으면 재시도 간격을 늘리고 짧은 무작위 대기 시간을 추가하세요.

분당 요청 수와 분당 토큰 수가 모두 한도 이내여도 slow_down 오류가 발생할 수 있습니다. 이 오류는 한도 소진 여부와 별개로 트래픽이 얼마나 빠르게 증가했는지를 나타냅니다.

일반적인 기준으로, 분당 입력 토큰 수(TPM)가 100만 개에 도달하면 이후 15분마다 트래픽을 최대 50%씩만 늘리세요. 트래픽 증가율 제한이 적용되는 정확한 시점은 모델과 트래픽 상황에 따라 달라질 수 있습니다.

종량제 트래픽이 증가율 제한에 자주 걸리는 엔터프라이즈 고객은 지원 대상 모델의 처리 용량을 더 정확하게 예측할 수 있도록 스케일 등급을 고려할 수 있습니다. GPT-5.6 이상 모델은 Reserved Tier를 참조하세요. 용량 등급에 관계없이 slow_down 응답에 대응하는 방법은 같습니다. Retry-After가 있으면 지정된 시간만큼 기다리고, 트래픽을 줄인 뒤 서서히 늘리세요.

기존 오류 처리기 업데이트하기

애플리케이션에서 이전 방식의 요청 제한 및 과부하 응답을 처리하고 있다면 HTTP 상태와 error.code를 모두 확인하세요.

• 이전에는 두 상황 모두 503 상태와 slow_down 코드를 반환하던 엔드포인트에서 이제 트래픽이 급증하면 429 상태와 slow_down 코드를 반환합니다. 모델 과부하 시에는 여전히 503 상태를 반환하지만 오류 코드는 server_is_overloaded입니다.
• 이전에는 이 두 상황으로 인해 작업 생성 전에 동영상 요청이 거부되면 429 상태, invalid_request_error 유형, rate_limit_exceeded 코드를 반환했습니다. 이제 트래픽이 급증하면 429 상태, rate_limit_error 유형, slow_down 코드를 반환합니다. 모델 과부하 시에는 503 상태, service_unavailable_error 유형, server_is_overloaded 코드를 반환합니다. 동영상 작업의 상태에 표시되는 오류는 별도로 처리해야 합니다.

SDK 오류 처리기에서는 429와 503을 모두 처리하세요. 예를 들어 Python, TypeScript, Ruby에서는 RateLimitError가 429에, InternalServerError가 503에 해당합니다. Java에서는 각각 RateLimitException과 InternalServerException을 사용합니다. 애플리케이션이 이전 응답 코드를 받을 가능성이 있는 동안에는 해당 코드도 계속 처리하세요. 다른 오류에서도 같은 HTTP 상태를 사용할 수 있으므로 복구 방법을 결정하기 전에 오류 응답 본문을 확인하세요.

스트리밍 요청에서 이러한 HTTP 오류 응답은 스트림이 시작되기 전에 반환됩니다. 스트리밍이 시작된 후에는 오류가 스트림 이벤트로 전달될 수 있습니다. 출력을 이미 받아 처리했다면 요청을 자동으로 다시 보내지 마세요.

요청 한도 오류를 줄이는 방법

OpenAI Cookbook의 Python 노트북에서는 요청 한도 오류를 피하는 방법을 설명합니다. API 요청을 일괄 처리하면서 요청 한도를 지키는 Python 스크립트 예제도 제공합니다.

프로그래밍 방식의 접근, 대량 처리, 소셜 미디어 자동 게시 기능을 제공할 때는 주의하세요. 신뢰할 수 있는 고객에게만 이러한 기능을 활성화하는 방안을 고려하세요.

자동화된 오용과 대규모 오용을 방지하려면 일간, 주간 또는 월간 사용 한도를 사용자별로 설정하세요. 한도를 초과하는 사용자에게는 추가 사용을 차단하거나 수동 검토 절차를 적용하는 방안을 고려하세요.

지수 백오프로 재시도하기

요청이 일시적인 요청 한도를 초과하면 API는 429 오류를 반환합니다. 응답에는 재시도하기까지 몇 초를 기다려야 하는지 알려주는 Retry-After 헤더가 포함될 수 있습니다. 이 값은 최소 대기 시간입니다. 적어도 이 시간만큼 기다리고, 여러 클라이언트가 동시에 재시도하지 않도록 짧은 무작위 대기 시간을 추가하세요.

각 OpenAI 공식 SDK는 재시도 설정에 따라 429 또는 503 응답을 받은 요청 중 재시도 대상인 요청을 자동으로 다시 보냅니다. Retry-After 처리 방식은 SDK 버전과 구성에 따라 다르며, 특히 대기 시간이 길 때 차이가 있습니다. 서버가 지정한 대기 시간을 모두 지원한다고 가정하지 말고 설치된 버전의 재시도 동작을 확인하세요.

서버가 지정한 유효한 대기 시간이 지원되거나 설정된 최대 재시도 대기 시간을 초과하면, 더 일찍 재시도하지 말고 재시도를 중단한 뒤 요청을 나중에 처리하세요. 대기 시간이 SDK의 한도를 초과해 SDK가 재시도하지 않으면 원래의 HTTP 오류를 반환할 수 있습니다. 취소와 시간 초과 오류는 별도로 처리하세요. 요청이 취소되거나 기한이 만료되면 해당 HTTP 오류를 반환하지 않고 재시도가 중단될 수 있습니다. 각 시도의 시간 제한이 반드시 전체 작업의 기한을 뜻하지는 않습니다.

자체 HTTP 클라이언트를 사용하는 경우 Retry-After 헤더가 있고 값이 유효하면 지정된 시간만큼 기다리세요. 헤더가 없거나 값이 유효하지 않으면 지터를 적용한 지수 백오프를 사용하세요. 시도 횟수와 재시도에 걸리는 총시간을 모두 제한하세요. 애플리케이션에서 재시도를 관리한다면 SDK의 재시도를 비활성화하거나 SDK가 수행하는 재시도까지 이 한도에 포함하세요. 그래야 재시도 루프가 중첩되어 요청 수가 몇 배로 늘어나는 일을 막을 수 있습니다. 할당량이나 결제 문제 등 직접 조치해야 하는 오류는 재시도하지 마세요.

지수 백오프는 요청이 실패하면 잠시 기다린 뒤 재시도하고, 재시도가 실패할 때마다 대기 시간을 늘리는 방식입니다. 요청이 성공하거나 설정한 재시도 한도에 도달할 때까지 이 과정을 반복합니다.

이 방식에는 다음과 같은 이점이 있습니다.

• 자동 재시도를 사용하면 프로그램이 비정상 종료되거나 데이터가 누락되는 일 없이 요청 한도 오류에서 복구할 수 있습니다.
• 지수 백오프를 사용하면 처음에는 빠르게 재시도하고, 몇 차례 실패가 이어지면 더 긴 간격을 두고 재시도할 수 있습니다.
• 대기 시간에 무작위 지터를 추가하면 여러 재시도가 한꺼번에 몰리는 것을 줄일 수 있습니다.

실패한 요청도 분당 한도에 포함되므로 같은 요청을 쉬지 않고 다시 보내는 방식은 효과가 없습니다.

다음 예제는 gpt-6-luna 모델을 지정해 Responses API에 보낸 요청을 재시도하는 방법을 보여줍니다. 각 래퍼는 시도 횟수를 제한하고 SDK의 기본 재시도 기능을 비활성화합니다.

아래 Python 예제는 서버에서 유효한 대기 시간을 제공하지 않을 때 사용하는 백오프 방식을 보여줍니다. 예제는 Retry-After를 확인하지 않습니다. 사용하기 전에 서버가 지정한 유효한 대기 시간을 처리하는 로직을 추가해 래퍼가 그보다 일찍 재시도하지 않도록 하세요. SDK 재시도를 비활성화하거나 애플리케이션의 재시도 한도에 포함하세요.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28from openai import OpenAI, RateLimitError
from tenacity import (
    retry,
    retry_if_exception_type,
    stop_after_attempt,
    wait_random_exponential,
)  # for exponential backoff

client = OpenAI(max_retries=0)


@retry(
    retry=retry_if_exception_type(RateLimitError),
    wait=wait_random_exponential(min=1, max=60),
    stop=stop_after_attempt(6),
    reraise=True,
)
def response_with_backoff(**kwargs):
    return client.responses.create(**kwargs)


response = response_with_backoff(
    model="gpt-6-luna",
    input="Say hello in one sentence.",
    reasoning={"effort": "none"},
    max_output_tokens=64,
)
print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import backoff
import openai
from openai import OpenAI

client = OpenAI(max_retries=0)


@backoff.on_exception(backoff.expo, openai.RateLimitError, max_tries=6)
def response_with_backoff(**kwargs):
    return client.responses.create(**kwargs)


response = response_with_backoff(
    model="gpt-6-luna",
    input="Say hello in one sentence.",
    reasoning={"effort": "none"},
    max_output_tokens=64,
)
print(response.output_text)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68# imports
import random
import time

import openai
from openai import OpenAI

client = OpenAI(max_retries=0)

# define a retry decorator


def retry_with_exponential_backoff(
    func,
    initial_delay: float = 1,
    exponential_base: float = 2,
    jitter: bool = True,
    max_retries: int = 10,
    errors: tuple = (openai.RateLimitError,),
):
    """Retry a function with exponential backoff."""

    def wrapper(*args, **kwargs):
        # Initialize variables
        num_retries = 0
        delay = initial_delay

        # Loop until a successful response or max_retries is hit or an exception is raised
        while True:
            try:
                return func(*args, **kwargs)

            # Retry on specific errors
            except errors:
                # Increment retries
                num_retries += 1

                # Check if max retries has been reached
                if num_retries > max_retries:
                    raise Exception(
                        f"Maximum number of retries ({max_retries}) exceeded."
                    )

                # Increment the delay
                delay *= exponential_base * (1 + jitter * random.random())

                # Sleep for the delay
                time.sleep(delay)

            # Raise exceptions for any errors not specified
            except Exception:
                raise

    return wrapper


@retry_with_exponential_backoff
def response_with_backoff(**kwargs):
    return client.responses.create(**kwargs)


response = response_with_backoff(
    model="gpt-6-luna",
    input="Say hello in one sentence.",
    reasoning={"effort": "none"},
    max_output_tokens=64,
)
print(response.output_text)

생성할 응답 크기에 맞게 max_tokens 줄이기

요청 한도를 계산할 때는 max_tokens와 요청의 문자 수를 기준으로 추정한 토큰 수 중 더 큰 값을 사용합니다. max_tokens 값은 예상 응답 크기에 최대한 가깝게 설정하세요.

요청 일괄 처리하기

즉시 응답을 받을 필요가 없다면 Batch API를 사용해 많은 요청을 한꺼번에 제출하고 실행할 수 있습니다. 이렇게 처리한 요청은 동기 요청 한도에 영향을 주지 않습니다.

동기 응답이 꼭 필요한 경우, OpenAI API에는 분당 요청 수 한도와 분당 토큰 수 한도가 별도로 적용됩니다.

분당 요청 수 한도에 도달했지만 분당 토큰 수에는 여유가 있다면 여러 작업을 하나의 요청에 묶어 처리량을 높일 수 있습니다. 특히 소형 모델을 사용할 때 이 방식으로 분당 더 많은 토큰을 처리할 수 있습니다.

여러 프롬프트를 묶어 보내는 방법은 일반 API 호출과 같습니다. prompt 매개변수에 문자열 하나 대신 문자열 목록을 전달하면 됩니다. Batch API 가이드에서 자세히 알아보세요.