codecamp

OpenAI API 速率限制

速率限制约束客户端在指定时间内访问API的次数或用量。本页解释限流机制、自动层级提升,以及常见错误的缓解方式。

为什么需要速率限制?

限制恶意请求洪泛和滥用,避免服务过载;防止单个组织占用过多资源,维持公平访问;管理整体基础设施负载,使多数用户获得稳定体验。

速率限制如何工作?

指标包括RPM(每分钟请求)、RPD(每天请求)、TPM(每分钟词元)、TPD(每天词元)、IPM(每分钟图像),某些流式音频模型还有每分钟音频分钟数。任一先达到就触发;例如RPM为20、TPM为150k时,即使20次请求各仅100词元,也已达到RPM。

Batch队列按某模型已排队输入词元计量,完成后释放队列占用。其他要点:

  • 限制在组织及项目层面,而非单用户;不同模型不同。
  • GPT-5.5等长上下文模型的长请求有独立限制,见Limits。
  • OpenAI批准的组织月度使用上限,与自行配置的支出限制独立。
  • 某些模型共享配额,例如列表中的共享TPM为3.5M,则该组所有模型调用合计占用此量。
  • 向量库摄入按向量库ID限流,/vector_stores/{vector_store_id}/files与/vector_stores/{vector_store_id}/file_batches共享每库300 RPM;大量摄入优先用file_batches。

用量层级

用量层级说明速率限制。组织、项目和 API 密钥是否有权访问模型,请另行检查。

付费层级Build、Launch、Grow随组织累计购买额度达到阈值自动提升,通常获得更高速率。来源快照如下,实际以账户为准:

层级 资格 月度使用上限
Free 位于支持地区 100美元
Build 累计购买5美元额度 500美元
Launch 累计购买100美元额度 5,000美元
Grow 累计购买500美元额度 200,000美元

Standard速率限制

在Settings → Organization → Limits的Rate limits查看;Usage Tiers下Upgrade tier可升级。它们与Ultrafast限额不同。

层级 模型系列 RPM TPM
Build Astra、Sol、Terra 5,000 1,000,000
Build Luna 5,000 2,000,000
Launch Astra、Sol、Terra 10,000 4,000,000
Launch Luna 10,000 10,000,000
Grow Astra、Sol、Terra 15,000 40,000,000
Grow Luna 30,000 180,000,000

支出限制

支出提醒达到金额只通知、不停止流量;硬上限达到后适用请求返回429。它们用于控制组织或项目月度支出,与上述批准使用上限分开。

响应头中的限额

除了账户页,HTTP响应头也可提供剩余请求、词元和重置时间:

字段 示例值 说明
Retry-After 56 临时限流时重试前至少等待的秒数(若存在)。
x-ratelimit-limit-requests 60 请求数上限。
x-ratelimit-limit-tokens 150000 词元上限。
x-ratelimit-remaining-requests 59 剩余请求数。
x-ratelimit-remaining-tokens 149984 剩余词元。
x-ratelimit-reset-requests 1s 请求额度重置前时间。
x-ratelimit-reset-tokens 6m0s 词元额度重置前时间。
x-ratelimit-limit-project-tokens 60000 项目词元上限。
x-ratelimit-remaining-project-tokens 57000 项目剩余词元。
x-ratelimit-reset-project-tokens 3s 项目词元额度重置时间。

项目头可能只在项目词元限制适用时出现。临时429和模型过载503可能有Retry-After,但它不意味着账单、配额等需要人工处理的错误能靠重试解决。

微调速率限制

可在面板查看,或通过API获取:

来源示例 1(bash):

## [中文] 查询组织微调速率限制,需要相应权限。
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、支持的端点,以及停用或可用性公告。
  2. 在 Playground 选择对应组织和项目。使用失败请求的 API 密钥,以及相同的 OpenAI-Organization 和 OpenAI-Project 请求头列出模型,比较两边结果。
  3. 请项目管理员检查模型权限和数据保留设置,并确认模型特定的访问要求及分批开放公告。
  4. 调整设置后刷新模型列表或 Playground。如果仍不可用,向支持团队提供模型 ID、组织和项目 ID、请求时间、错误信息,以及可用的 x-request-id。请保管好 API 密钥。

缓解错误

应对流量骤增与模型过载

状态 类型 代码 含义与措施
429 rate_limit_error slow_down 增长过快;遵守Retry-After,降低流量后逐渐增加。
503 service_unavailable_error server_is_overloaded 模型暂时过载;遵守Retry-After后重试,持续发生则增加等待。

没有响应头时采用增加间隔并带随机抖动的重试。slow_down即使未超过RPM/TPM也可能发生,它限制增长速度。经验规则是达到100万输入TPM后,每15分钟增长不超过50%,触发点仍随模型与流量变化。

经常触发的Enterprise按量客户可考虑Scale Tier;GPT-5.6及以后见Reserved Tier。容量方案不能替代正确等待与渐进爬升。

更新已有错误处理器

某些旧端点原来对两类情况都返回503 slow_down;现在骤增为429 slow_down,过载为503 server_is_overloaded。视频任务创建前拒绝原先可能是429 invalid_request_error/rate_limit_exceeded,现在分别采用上述429和503;视频作业状态内错误是另一情况。

SDK同时处理429与503,并检查error.code。Python、TypeScript、Ruby分别用RateLimitError和InternalServerError;Java用RateLimitException和InternalServerException。仍可能收到旧响应时需保留兼容。其他错误也可使用相同状态码,先看正文再决定恢复。

流式请求开始前适用这些HTTP错误;开始后错误可能作为流事件到达。已经消费输出时,不能自动重放整次请求。

还可以采取哪些措施?

参考Cookbook及并行请求脚本。对编程访问、批量功能、自动社交发布应谨慎,只向可信客户开放;给单个用户设置日/周/月用量限制,超额可硬封顶或人工复核,防止自动化滥用。

指数退避重试

有效Retry-After是最短等待时间,可再加少量随机延迟,避免同时重试。官方SDK会按配置重试合格429/503,但对长等待的支持因版本不同;超过支持或配置的最大等待时,应停止重试并延后任务,不能提前重试。SDK拒绝过长等待时可能返回原HTTP错误。

取消与超时需单独处理:取消请求或总截止时间到达可能终止重试而不返回原HTTP错误;每次尝试的超时不一定是整个操作的截止时间。

自有HTTP客户端应先遵守有效Retry-After;缺失/无效再退回带抖动的指数退避。同时限制尝试次数及总耗时,关闭SDK重试或把它计入预算,避免嵌套放大。不重试账单、配额等需要先采取行动的错误。

指数退避让首次失败后短暂等待,连续失败则逐步增长,直到成功或达到上限。优点是自动恢复、首次尝试较快、持续失败降低压力,随机抖动减少重试碰撞。失败请求也占每分钟限额,持续立即重发无效。

以下示例使用 Responses API 向 gpt-6-luna 发送请求。每个重试封装都限制尝试次数,并关闭 SDK 内置重试。

这些Python包装器没有读取Retry-After,使用前须补充有效服务端等待提示处理,并关闭或统计SDK重试。本地未运行旧模型。

示例1:Tenacity库

Tenacity是Apache 2.0许可的通用Python重试库。用tenacity.retry装饰器及wait_random_exponential增加随机指数退避:

来源示例 2(python):

## [中文] 对 Responses 请求执行有限次数的退避重试。SDK 内置重试已关闭。
from 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)

它是第三方工具,OpenAI不保证其可靠性或安全性。

示例2:backoff库

backoff也提供退避重试装饰器:

来源示例 3(python):

## [中文] 对 Responses 请求执行有限次数的退避重试。SDK 内置重试已关闭。
import 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)

同样属于第三方,OpenAI不提供可靠性或安全保证。

示例3:手动实现退避

不使用第三方库时可从以下实现开始。来源不保证该方案安全性或效率,需按应用完善。

来源示例 4(python):

## [中文] 对 Responses 请求执行有限次数的退避重试。SDK 内置重试已关闭。
## 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与按请求字符量估计词元数的较大值,因此应让生成上限接近期望输出。具体参数名仍需遵循所选端点和模型,不要直接把旧参数套入新接口。

合并请求

无需即时响应时使用异步Batch API,不消耗同步速率池。需要同步时,若RPM已满而TPM仍有空间,可在单次请求内合并多个任务,提高吞吐,尤其适合较小模型。

来源还介绍旧Completions的prompt字符串数组方式;这是相应端点的用法,与Batch API文件作业不同,不能推定所有现代接口都接收该参数。

OpenAI Decisions 决策API
OpenAI API 错误代码
温馨提示
下载编程狮App,免费阅读超1000+编程语言教程
取消
确定
目录

其他能力与进阶指南

Embeddings 接口参考

审计日志接口参考

关闭

MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }