Error 429 rate_limit_error en la API de Claude: qué significa y cómo resolverlo

429 significa "más despacio", no "te has quedado sin dinero". La diferencia importa: para uno hay que esperar y para el otro recargar; confundirlos lleva a horas de depuración en el lugar equivocado.

El error

resposta (HTTP 429)

{
  "type": "error",
  "error": { "type": "rate_limit_error",
             "message": "Number of requests has exceeded your rate limit" }
}

Causas y soluciones de un vistazo

Causa	Solución
Solicitudes por minuto por encima del límite de tu cuenta	Ponlas en cola y limita la concurrencia en el cliente, en lugar de enviarlo todo de una vez.
Tokens por minuto por encima del límite	Los prompts largos consumen la cuota de tokens mucho antes que la cuota de solicitudes. Reduce el contexto o divide el trabajo.
Varios procesos utilizan la misma clave	El límite corresponde a la clave, no al proceso. Los workers paralelos se acumulan contra la misma cuota.
Reintentos sin backoff	Reintentar inmediatamente te mantiene permanentemente por encima del límite. El backoff exponencial con jitter es obligatorio.

Respeta retry-after cuando aparezca

Cuando la respuesta incluye el encabezado retry-after, no es una sugerencia: es el tiempo exacto tras el cual la solicitud vuelve a aceptarse. Esperar menos garantiza otro 429.

retry_after.py

import time
from openai import APIStatusError

try:
    resp = client.chat.completions.create(model=MODELO, messages=msgs)
except APIStatusError as e:
    if e.status_code == 429:
        espera = float(e.response.headers.get("retry-after", 5))
        time.sleep(espera)
        resp = client.chat.completions.create(model=MODELO, messages=msgs)
    else:
        raise

Limita la concurrencia en el origen

La causa más común no es el volumen total, sino el pico: veinte solicitudes enviadas en el mismo instante superan un límite que sesenta solicitudes distribuidas en un minuto no superarían. Un semáforo resuelve lo que el retry por sí solo no puede.

concorrencia.py

import asyncio

LIMITE = asyncio.Semaphore(4)   # no máximo 4 chamadas simultâneas

async def chamar(msgs):
    async with LIMITE:
        return await client.chat.completions.create(
            model=MODELO, messages=msgs)

Confirma que es un límite y no un saldo

Un 429 nunca significa falta de créditos; eso es 402. Si tus logs mezclan ambos, sepáralos por estado antes de investigar: la solución para 429 es la temporización y la de 402 es recargar. Repetir un 402 falla para siempre.

Si llamas a través de Kunavo

En Kunavo, los límites son por clave y el saldo es una billetera prepago independiente, por lo que ambos casos aparecen con estados diferentes: 429 para el límite de velocidad y 402 cuando el saldo no cubre la llamada; nunca uno disfrazado del otro. Las solicitudes rechazadas no se cobran. Las tarifas por token, que determinan cuánto consume cada llamada del saldo, están en nuestra guía de precios de la API de Claude.

Preguntas frecuentes

¿429 significa que se agotaron mis créditos?

No. La falta de saldo es 402. El 429 se refiere a la velocidad: enviaste demasiadas solicitudes o tokens en poco tiempo, y esperar lo resuelve.

¿Cuánto tiempo debo esperar?

Si aparece el encabezado retry-after, exactamente ese tiempo. Sin él, aplica un backoff exponencial a partir de 1–2 segundos con jitter, hasta un máximo de 30–60 segundos.

¿Aumentar el límite lo resuelve?

Ayuda si el volumen es realmente alto, pero la mayoría de los 429 provienen de picos breves. Limitar la concurrencia suele resolverlo sin cambiar ningún límite.

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.