Claude API 429 rate_limit_error: causas y una solución eficaz

Un 429 de la API de Claude significa que superaste uno de los límites por minuto de Anthropic: solicitudes, tokens de entrada o tokens de salida. La solución rara vez consiste en «esperar más»: hay que respetar retry-after, añadir backoff con jitter y suavizar los picos. Aquí tienes la guía completa.

El error

response (HTTP 429)

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-minute rate limit"
  }
}

Causas y soluciones de un vistazo

Causa	Solución
Límite de solicitudes por minuto (RPM) alcanzado	Pon las solicitudes en cola en el cliente; respeta el encabezado retry-after antes de reintentar.
Límite de tokens de entrada por minuto (ITPM) alcanzado: prompts grandes, pocas solicitudes	Reduce el contexto recuperado y activa la caché de prompts para que los tokens almacenados en caché dejen de contar en tu contra en los planes compatibles.
Límite de tokens de salida por minuto (OTPM) alcanzado	Establece max_tokens de forma realista: OTPM suele ser el primer límite para las generaciones largas.
Tráfico en ráfagas (cron ejecuta todo en el minuto 00 de cada hora)	Añade jitter a los horarios; distribuye los trabajos por lotes a lo largo del minuto.

Lee la respuesta antes de reintentar

Anthropic devuelve un encabezado retry-after con los segundos que debes esperar, y el mensaje de error indica qué límite superaste. Reintentar al instante sin leerlo es la forma en que un solo 429 se convierte en una tormenta de 429.

Añade backoff exponencial con jitter

Reintenta solo los estados reintentables (429, 500, 529), nunca los errores de autenticación o validación. Este fragmento funciona sin cambios directamente contra Anthropic o contra cualquier endpoint compatible con OpenAI:

backoff.py

import time, random
from openai import OpenAI, APIStatusError

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

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

Reduce los tokens, no solo las solicitudes

Si el mensaje indica límites de tokens, el backoff por sí solo no te salvará. Reduce los fragmentos recuperados, limita max_tokens y activa la caché de prompts; un prompt de sistema grande y estable al 10 % de la tasa de entrada también alivia la presión sobre ITPM.

Si llamas a través de Kunavo

Llamar a Claude a través de Kunavo no elimina mágicamente los límites de tasa, pero cambia la economía del fallo: las solicitudes fallidas (incluidos los 429) nunca se facturan, y el panel de uso por clave muestra exactamente qué clave y modelo están generando la ráfaga para que puedas suavizarla. El mismo fragmento de backoff anterior funciona tal cual; solo cambia base_url. Los límites de solicitudes son un techo de rendimiento, no un precio. Para saber cuánto cuesta realmente una llamada a Claude por 1M de tokens, con la lista oficial de Anthropic junto a la nuestra, consulta lista de precios de la API de Anthropic Claude.

Preguntas frecuentes

¿Actualizar mi nivel de Anthropic elimina los 429?

Los niveles superiores elevan los límites por minuto, por lo que los 429 son menos frecuentes, pero cualquier límite fijo puede alcanzarse con una ráfaga. El código de producción necesita backoff independientemente del nivel.

¿Debo reintentar un 429 inmediatamente?

No: respeta el encabezado retry-after (o usa backoff exponencial con jitter si está ausente). Los reintentos inmediatos prolongan la ventana limitada y pueden convertirse en un bloqueo más largo.

¿Las solicitudes 429 fallidas cuestan dinero?

Anthropic no cobra por las solicitudes rechazadas, y Kunavo tampoco: las solicitudes fallidas nunca se facturan. El coste de un 429 es latencia, no dinero.

Guías relacionadas

Encontrarás más detalles sobre el significado de los errores en referencia de errores; obtener una clave lleva un minuto mediante registro y la guía de autenticación.