速率限制与错误

限制按密钥生效，同时约束请求数量和 token 吞吐量。每个响应都携带当前状态：

响应头	含义
`x-ratelimit-limit-requests`	当前窗口允许的请求数量。
`x-ratelimit-remaining-requests`	当前窗口剩余的请求数量。
`x-ratelimit-reset-requests`	请求计数器重置前的剩余秒数。
`x-ratelimit-limit-tokens`	当前窗口允许的 token 数量。
`x-ratelimit-remaining-tokens`	当前窗口剩余的 token 数量。
`x-ratelimit-reset-tokens`	token 计数器重置前的剩余秒数。

超过限制时返回 429。请等待 Retry-After 响应头指定的时间后重试，并使用带随机抖动的指数退避，避免并发任务在同一时刻再次发送请求：

import random
import time

import openai

def with_retries(fn, attempts=5):
    for attempt in range(attempts):
        try:
            return fn()
        except openai.RateLimitError as err:
            if attempt == attempts - 1:
                raise
            retry_after = getattr(err, "response", None)
            delay = float(retry_after.headers.get("Retry-After", 0)) if retry_after else 0
            time.sleep(max(delay, 2**attempt) + random.random())

OpenAI 官方 SDK 已会对 429 和 5xx 自动重试几次。如需调整行为，可在创建客户端时设置 max_retries；仅在 SDK 未覆盖的场景中使用自定义重试逻辑。

错误

失败响应使用常规 HTTP 状态码，并采用统一的响应体：

{
  "error": {
    "message": "Human-readable description of what went wrong.",
    "type": "invalid_request_error",
    "code": "context_length_exceeded"
  }
}

状态码	含义	处理方式
`400`	请求格式错误或参数不受支持	修正请求，重试无效。参见模型与参数。
`401`	密钥缺失或无效	检查 `Authorization` 请求头。参见密钥与身份验证。
`403`	密钥无权访问此模型	申请权限或选择其他模型。
`404`	接口不存在或模型已下线	重新检查路径和 `GET /v1/models`。
`429`	触发速率限制或额度耗尽	退避重试，或提高限额。额度信息参见用量与计费。
`5xx`	上游或网关故障	退避后重试。

请记录 error.code，而不是匹配 error.message 的文本；错误码稳定，错误消息则可能变化。

用量与计费

每次请求的 token 用量，以及查看剩余额度的位置。

速率限制与错误

错误

用量与计费

本页目录