Límites de velocidad de la API de OpenAI: cuál alcanzas, cómo leerlo y el reintento que lo soluciona

Un 429 de OpenAI significa que has superado uno de cinco límites máximos, y el primer trabajo consiste en averiguar cuál, porque las soluciones apuntan en direcciones opuestas. Esta página explica qué mide cada límite, cómo leer la respuesta directamente de las cabeceras, la lógica de reintentos que realmente detiene los errores y qué hacer cuando un backoff correcto no basta.

Verificado 30 de septiembre de 2026 con la documentación de límites de velocidad de OpenAI.

Cinco límites, cualquiera de los cuales puede activarse

El límite que se agote primero activa el error, así que «estamos muy lejos del límite de tokens» no es una razón para descartar un límite de velocidad: quizá estés lejos de TPM y exactamente en RPM. Los límites se aplican por organización y por modelo, no por clave: crear claves adicionales no crea cuota adicional.

Cómo se ve un 429

HTTP/1.1 429 Too Many Requests
retry-after: 12
x-ratelimit-limit-requests: 500
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 12s
x-ratelimit-limit-tokens: 200000
x-ratelimit-remaining-tokens: 143820
x-ratelimit-reset-tokens: 17s

{
  "error": {
    "message": "Rate limit reached for gpt-5.4 in organization org-... on requests per min (RPM).",
    "type": "requests",
    "code": "rate_limit_exceeded"
  }
}

Todo lo que necesitas está en esa respuesta. El cuerpo nombra la dimensión («requests per min (RPM)»), y las cabeceras indican el límite máximo exacto, lo que queda y cuándo se recupera.

Niveles de uso

Tus límites máximos los determina tu nivel de uso, que OpenAI aumenta automáticamente a medida que se acumula el gasto acumulado:

No se reproducen deliberadamente aquí: las cifras de RPM y TPM por modelo. Difieren según el modelo, cambian cuando se lanzan modelos nuevos y pueden ajustarse por cuenta, así que cualquier tabla publicada en una página de terceros es una estimación con fecha. Las dos fuentes autorizadas para tu propia cuenta son la página de límites del panel de OpenAI y las cabeceras x-ratelimit-* de cada respuesta que ya realizas. Lee las cabeceras.

La solución: respeta Retry-After y luego añade jitter

La recomendación documentada de OpenAI es aplicar backoff exponencial con jitter, siguiendo Retry-After cuando la respuesta incluya uno. Ambas partes importan. Sin la cabecera, quizá reintentes demasiado pronto; sin jitter, todos los clientes que fallaron en el mismo instante reintentan en el mismo instante y vuelven a fallar juntos: una estampida que convierte un segundo malo en un minuto malo.

import random, time
import openai

client = openai.OpenAI()

def call_with_backoff(fn, *, max_attempts=6, base=0.5, cap=30.0):
    """Retry 429s: honour Retry-After when present, jittered backoff otherwise."""
    for attempt in range(max_attempts):
        try:
            return fn()
        except openai.RateLimitError as err:
            if attempt == max_attempts - 1:
                raise
            # The server's own answer beats any formula you invent.
            retry_after = (err.response.headers or {}).get("retry-after")
            if retry_after:
                delay = float(retry_after)
            else:
                # Full jitter: sleep a random point in [0, 2^n * base], capped.
                # Without the randomness every client that failed at the same
                # instant retries at the same instant and fails again together.
                delay = random.uniform(0, min(cap, base * 2**attempt))
            time.sleep(delay)

resp = call_with_backoff(lambda: client.responses.create(
    model="gpt-5.4",
    input="Summarise this changelog in three bullets.",
))

La misma estructura en TypeScript:

import OpenAI from "openai";

const client = new OpenAI();
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

export async function callWithBackoff<T>(
  fn: () => Promise<T>,
  { maxAttempts = 6, baseMs = 500, capMs = 30_000 } = {},
): Promise<T> {
  for (let attempt = 0; ; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const status = (err as { status?: number }).status;
      if (status !== 429 || attempt === maxAttempts - 1) throw err;

      const retryAfter = (err as { headers?: Headers }).headers?.get("retry-after");
      const delay = retryAfter
        ? Number(retryAfter) * 1000
        : Math.random() * Math.min(capMs, baseMs * 2 ** attempt);
      await sleep(delay);
    }
  }
}

const resp = await callWithBackoff(() =>
  client.responses.create({ model: "gpt-5.4", input: "Hello" }),
);

Los SDK oficiales ya reintentan los errores 429 por ti, así que la mayoría de las aplicaciones solo necesitan esto cuando envuelven las llamadas en su propio cliente HTTP o cuando quieren un comportamiento diferente: un límite más largo para el trabajo en segundo plano o un fallo inmediato para una solicitud visible para el usuario en la que esperar 12 segundos sea peor que recibir un error.

Supervisa antes de que falle

Los contadores están en cada respuesta, no solo en los fallos. Registrar los valores restantes convierte la limitación de velocidad de un incidente en un indicador: puedes ver cómo se reduce el margen con días de antelación a que un lanzamiento lo agote.

# Log the remaining counters on every response, not just on failures.
# By the time you see a 429 the useful signal is already an hour old.
resp = client.responses.with_raw_response.create(model="gpt-5.4", input="…")
h = resp.headers

log.info(
    "openai_quota model=%s req_left=%s tok_left=%s reset_req=%s reset_tok=%s",
    "gpt-5.4",
    h.get("x-ratelimit-remaining-requests"),
    h.get("x-ratelimit-remaining-tokens"),
    h.get("x-ratelimit-reset-requests"),
    h.get("x-ratelimit-reset-tokens"),
)

parsed = resp.parse()   # the normal response object

Dos hábitos que conviene adoptar junto con esto: alerta cuando x-ratelimit-remaining-tokens caiga por debajo de una fracción determinada del límite, en lugar de hacerlo por el número de 429, y añade jitter a los programas, no solo a los reintentos. Un cron que lo ejecuta todo en :00 fabrica su propia ráfaga.

Cuándo el backoff no es la respuesta

Un backoff correcto corrige las ráfagas. No hace nada ante una demanda sostenida por encima de tu límite máximo; en ese caso, los reintentos solo retrasan el fallo. Las soluciones estructurales, aproximadamente en orden de esfuerzo, son:

• Limita la salida. Los tokens de razonamiento se facturan y cuentan como salida, así que una generación sin límites es la forma más rápida de consumir TPM.
• Reduce el contexto recuperado. Con un límite de TPM, reducir a la mitad los fragmentos recuperados duplica tu capacidad de procesamiento gratis.
• Dimensiona correctamente el modelo. Un paso de clasificación no necesita un modelo de vanguardia, y los modelos pequeños tienen su propio presupuesto separado.
• Separa las cargas de trabajo. Los trabajos por lotes y el tráfico sensible a la latencia compitiendo por un único límite a nivel de organización es la versión autoinfligida más habitual de este problema.
• Aumenta el nivel. Los niveles avanzan con el gasto acumulado, así que a menudo esto ya está ocurriendo.

Distribuir la carga entre familias de modelos

El último punto de esa lista es donde una pasarela demuestra su utilidad. Kunavo ofrece una API compatible con OpenAI: el mismo SDK, la misma estructura de llamada y una sola clave, entre varias familias de modelos, de modo que mover una carga de trabajo fuera de un límite saturado consiste en cambiar el nombre del modelo, no en realizar una segunda integración:

from openai import OpenAI

client = OpenAI(
    api_key="sk-kn-...",
    base_url="https://api.kunavo.com/v1",
)

# Same SDK, same call shape — the model string chooses the family.
client.chat.completions.create(
    model="gpt-5-6-terra",            # or claude-sonnet-5, claude-haiku-4-5, …
    messages=[{"role": "user", "content": "Hello"}],
)

En concreto: el trabajo por lotes de resumen que competía con tu tráfico de producción puede ejecutarse en claude-haiku-4-5 a $0.70 / $3.50 por 1M, mientras la ruta sensible a la latencia permanece en gpt-5-6-terra ($0.70 / $4.20) o claude-sonnet-5 ($1.40 / $7.00). Familia diferente, cola diferente.

Ten claro qué hace esto y qué no hace. Elimina el cuello de botella de una sola cuenta y un solo modelo, y te ofrece una alternativa para la conmutación por error. No crea capacidad: si tu volumen total supera realmente lo que permite cualquier nivel, la respuesta sigue siendo aumentar el nivel o hacer menos trabajo. Las tarifas de todos los modelos están en la página de precios, y la guía equivalente para los límites de Anthropic está en Claude API 429 rate_limit_error.

Preguntas frecuentes