Rate limits, reintentos y observabilidad

Cuando tu aplicación le pide algo a la API de Claude y de repente deja de responder con un error 429, no es un bug: es un rate limit. Entender este límite es clave para cualquier desarrollador que integre Claude, Google o cualquier servicio con cuota, porque ningún servicio en el mundo te deja pedir infinito.

Por qué ningún servicio te deja pedir infinito

Todos los servicios ponen un tope a cuánto puedes solicitar por minuto: ni Claude, ni Google, ni tu banco escapan de esto [00:11]. Si le pides algo mil veces seguidas a Claude, en algún punto deja de responderte y devuelve un error 429.

Antes de escribir una sola línea de código para manejarlo, necesitas entender cuatro cosas: cómo funciona el límite, cómo se mide, cuándo se rellena y qué te dice la API cuando lo alcanzas [00:23].

¿Qué es el error 429 en una API? Es el código que indica que superaste el límite de peticiones permitidas. Significa "demasiadas solicitudes" y la API te pide esperar antes de reintentar.

Cómo se mide el límite en la API de Claude

Acá viene lo interesante: ese límite no es por API key, es por organización entera [00:38]. Puedes tener 10 API keys y todas comparten el mismo límite de capacidad. No sirve multiplicar keys para esquivar el tope.

El límite se mide por dos cosas concretas [00:47]:

• Los requests por minuto (cuántas peticiones haces).
• Los tokens por minuto (cuánta información procesas).

En la documentación real existen dos límites separados de tokens, el input y el output, pero la idea es la misma: te quedas sin cuota si te pasas en cualquiera de los dos por separado [00:52].

Por qué mandar todo en ráfaga te tira el error

El límite no se resetea de golpe cada minuto, se va rellenando todo el tiempo [01:08]. Por eso mandar todo en una sola ráfaga puede tirarte el error aunque en teoría todavía tengas cuota disponible.

Si estás dentro del límite, recibes una respuesta exitosa y todo funciona normal. Pero si te excedes, llega el 429 [01:20].

Cómo resolver el error 429 con retry-after

Lo bueno es que la API te da la solución en la misma respuesta. Usa un header llamado retry-after que te dice exactamente cuántos segundos esperar antes de reintentar [01:28].

Hay tres cosas que debes recordar sobre estos límites [01:33]:

1. Los límites son por organización, no por API key.
2. Cada respuesta trae headers con cuánto te queda, y conviene loguearlos para monitorear antes de que explote el error.
3. Los límites suben solos a medida que usas más la API, así que el número que ves hoy puede ser otro en un mes.

Este último punto es útil: si empiezas con poca cuota, tu uso constante la va escalando con el tiempo.

¿Para qué sirve el header retry-after? Le indica a tu aplicación cuántos segundos esperar tras un error 429 antes de volver a intentar. Es la instrucción directa de la API para no seguir saturando el servicio.

Qué es el backoff exponencial y cómo funciona

El backoff exponencial es una estrategia para reintentar una operación fallida esperando cada vez más tiempo [02:11]. La lógica es simple y evita que sigas golpeando la API mientras está saturada.

El flujo funciona así [02:19]:

• Llamas a la API y recibes un error 429.
• El header retry-after te dice que esperes 12 segundos.
• Esperas, reintentas y si todo va bien, obtienes respuesta exitosa.
• Si vuelve a fallar con otro 429, la espera se duplica: pasa de 12 a 24 segundos, luego 48, luego 96, hasta llegar a un máximo de intentos definido.

Esa duplicación progresiva es lo que hace "exponencial" a la estrategia. Cada fallo aumenta la pausa, dándole aire al servicio para recuperarse.

¿Cuál es la diferencia entre retry-after y backoff exponencial? Retry-after es el dato que la API te entrega con los segundos a esperar. El backoff exponencial es la estrategia que duplica ese tiempo en cada reintento fallido.

Con estos conceptos claros ya tienes lo necesario sobre rate limits antes de programar. El siguiente paso es llevar el proyecto a producción usando Railway y empaquetarlo todo con FastAPI [03:00]. ¿Ya te topaste con un 429 en tus proyectos? Cuéntame cómo lo resolviste.