Solución: Aparece el mensaje 'Demasiadas solicitudes' (Rate limit 429) en Capitan o la API

Guía paso a paso para comprender los límites de tasa de peticiones (Rate Limiting) en WaclisCAL, resolver bloqueos temporales por código HTTP 429 e implementar buenas prácticas de consumo eficiente en integraciones y agentes de IA.

1. Síntoma

Al interactuar con el Agente de IA Capitan por WhatsApp, o al ejecutar sincronizaciones automáticas mediante la API REST v1, el sistema devuelve un error HTTP 429 Too Many Requests con el mensaje:

"Demasiadas solicitudes en un período corto de tiempo. Por favor espere unos momentos antes de reintentar."

2. Causas probables

Para proteger la estabilidad del servidor y prevenir ataques de denegación de servicio o bucles infinitos en scripts externos, WaclisCAL aplica límites automáticos de peticiones por minuto:

1. Límites de escritura alcanzados: Se enviaron más de 30 solicitudes de creación o cancelación (POST, DELETE) en menos de 60 segundos con el mismo token o dirección IP.
2. Límites de lectura alcanzados: Se realizaron más de 120 consultas de disponibilidad o eventos (GET) en menos de un minuto.
3. Bucle infinito en una automatización externa: Un flujo mal configurado en Make, n8n o un script en Python quedó atrapado en un bucle consultando la API repetidamente sin pausas.
4. Múltiples agentes o clientes utilizando el mismo token: Se configuró la misma clave de API en decenas de instancias simultáneas que consumen la cuota de forma combinada.

3. Comprobaciones previas

1. Revisa la cabecera HTTP Retry-After que devuelve la respuesta 429: indica la cantidad de segundos exactos que debes esperar para que el contador se reinicie (típicamente entre 30 y 60 segundos).
2. Si utilizas Make o herramientas de automatización, revisa el historial de ejecuciones recientes para detectar si un flujo se ejecutó docenas de veces en el mismo minuto.
3. Si el aviso ocurrió en WhatsApp con Capitan, comprueba si un usuario envió ráfagas masivas de mensajes en pocos segundos.

4. Solución paso a paso

Paso 1: Espera el restablecimiento automático de la ventana de tiempo

1. Los límites de WaclisCAL operan en ventanas móviles de 60 segundos.
2. Suspende temporalmente las peticiones hacia la API durante 60 segundos.
3. Una vez transcurrido este minuto, la cuota se restablecerá automáticamente al 100% sin necesidad de reiniciar servicios ni generar nuevos tokens.

Paso 2: Implementa pausas y reintentos exponenciales en tus scripts

1. En tu código de integración, nunca reintentes de inmediato tras recibir un error 429.
2. Implementa el patrón Exponential Backoff con Jitter (retroceso exponencial):

- Primer reintento: esperar 2 segundos.

- Segundo reintento: esperar 4 segundos.

- Tercer reintento: esperar 8 segundos.

1. Lee el encabezado Retry-After de la respuesta y programa la pausa exactamente por el valor indicado.

Paso 3: Optimiza el consumo con Webhooks en lugar de Polling

1. Si tu aplicación consulta la API cada 10 segundos para ver si hay reservas nuevas:

- Elimina las consultas repetitivas (Polling).

- Configura un Webhook en WaclisCAL para que sea nuestro servidor el que avise a tu sistema solo cuando ocurra una reserva real.

- Esta simple optimización reduce el consumo de peticiones en más de un 95%.

Paso 4: Separa tokens para diferentes herramientas

1. Si utilizas la API en Make, en tu app móvil y en asistentes MCP, genera un token dedicado para cada una.
2. De esta forma, si una herramienta realiza un consumo intensivo, no afectará los límites de las demás.

5. Cómo verificar que quedó resuelto

1. Tras pausar las peticiones durante 60 segundos, ejecuta una llamada de lectura simple:

curl -i -X GET "https://cal.waclis.com/api/wacliscal/v1/event-types" \
-H "Authorization: Bearer wcal_evt_live_tu_token"

1. La respuesta debe devolver un código HTTP 200 OK confirmando que la ventana de cuota está nuevamente operativa.

6. Cuándo escalar el problema

Si tu negocio gestiona volúmenes corporativos extraordinarios y requiere una cuota ampliada de peticiones por minuto para un proyecto de gran escala:

• Contacta al equipo de cuentas corporativas de Waclis para solicitar una asignación de límite de tasa personalizado (Custom Rate Limit) para la infraestructura de tu organización.

7. Artículos relacionados

• Integra WaclisCAL con tus propios sistemas mediante la API REST v1 oficial
• Configura Webhooks para conectar WaclisCAL con tus sistemas internos y bases de datos
• Genera y administra tokens de acceso seguros por Tipo de Evento
• Activa el Agente de IA Capitan para que atienda y agende turnos por WhatsApp