Skip to main content
YCloud limita las solicitudes de la API dentro de una ventana de tiempo. Los límites se aplican a una cuenta, a un remitente o a un grupo de endpoints. Las solicitudes que exceden un límite devuelven HTTP 429 Too Many Requests con la respuesta de error estándar .

Límites de la API de mensajería

rps significa solicitudes por segundo (rps). Un remitente es un número de teléfono comercial de WhatsApp. La mayoría de los endpoints tienen un límite de 200 rps por cuenta. Los endpoints de envío de WhatsApp utilizan los límites por remitente indicados anteriormente. Consulta la documentación de rendimiento de Meta para las actualizaciones automáticas.

Envíos directos y en cola de WhatsApp

YCloud mide los dos endpoints de envío de WhatsApp por separado. El endpoint en cola /v2/whatsapp/messages acepta hasta 200 rps por remitente, mientras que YCloud envía los mensajes en cola a Meta a 60 rps. La aceptación en la cola no significa que Meta haya aceptado o entregado el mensaje. Evita enviar a una tasa alta a través de ambos endpoints con el mismo remitente al mismo tiempo. Los envíos directos y en cola siguen utilizando el mismo número de teléfono comercial de WhatsApp, por lo que su tráfico combinado puede alcanzar el límite de Meta y provocar fallos.

Límites de la API de gestión

La mayoría de las API sin una política documentada por separado son API de gestión. Estos endpoints comparten una cuota de cuenta: 200 solicitudes por segundo y 10 000 solicitudes por hora. Se aplican ambos límites; no puedes mantener 200 rps durante una hora entera. Las solicitudes a un endpoint de gestión consumen la cuota disponible para los demás. La política compartida incluye:
  • /v2/balance
  • /v2/webhookEndpoints/*
  • /v2/whatsapp/businessAccounts/*
  • /v2/whatsapp/phoneNumbers/*
  • /v2/whatsapp/templates/*
  • /v2/whatsapp/messages/{id}
  • Otras API sin una política documentada por separado

Leer encabezados de límite de tasa

YCloud incluye información de límite de tasa en la mayoría de las respuestas de la API. Lee los encabezados cuando estén presentes en lugar de asumir que todos los endpoints tienen la misma cuota.
Los encabezados RateLimit-* están en fase beta y pueden cambiar. El formato de encabezado documentado de YCloud sigue la especificación draft-06 de límite de tasa del IETF. Trata los parámetros de política como informativos y mantén tu cliente tolerante a parámetros adicionales.

Ejemplo: cuota compartida por hora agotada

La cuenta ha agotado su cuota compartida de 10 000 solicitudes por hora . Espera al menos 1800 segundos antes de enviar otra solicitud contra esa cuota. Cambiar a un endpoint de gestión diferente no proporciona una cuota nueva.

Gestionar una respuesta 429

  1. Pausa las solicitudes que compartan la cuota agotada de la cuenta o del remitente.
  2. Respeta Retry-After cuando esté presente. No reintentes antes de que expire ese retraso.
  3. Reduce la concurrencia y añade retroceso exponencial con jitter.
  4. Limita los reintentos mediante un recuento de intentos o el tiempo límite de tu aplicación.
  5. Registra el endpoint, el método HTTP, el code de error, requestId y la hora de la solicitud. Excluye claves de API y datos personales.
Si una respuesta exitosa incluye Retry-After, retrasa las solicitudes posteriores; no vuelvas a enviar la solicitud que ya se completó correctamente. Monitorea RateLimit-Remaining y RateLimit-Reset para reducir la velocidad antes de que se agote la cuota.

Reintentar con retroceso y jitter

Este ejemplo de JavaScript trata Retry-After como una espera mínima. El límite de retroceso restringe el retraso de jitter de la aplicación; no acorta la espera solicitada por el servidor. Las configuraciones de intentos y retraso son decisiones de la aplicación, no límites de la API.
Aplica este ejemplo solo cuando sea seguro reintentar la operación. Para esperas prolongadas, utiliza una cola programada para que un worker no necesite permanecer activo.

Controlar la concurrencia y los reintentos

Utiliza una cola acotada y un límite de workers compartido. Evita bucles de reintento independientes donde cada uno asuma que toda la cuota de la cuenta o del remitente está disponible. Restablece el tráfico gradualmente una vez finalizada la limitación. Un POST repetido puede crear otro recurso o enviar otro mensaje. Verifique primero la guía de reintentos del endpoint y el resultado que tenga almacenado. Siempre que sea compatible, mantenga un externalId estable, pero no lo considere una clave de idempotencia universal. Guarde el ID de respuesta de YCloud y concilie los resultados ambiguos antes de volver a enviar. Supervise el volumen de solicitudes, las respuestas 429, la latencia, los recuentos de reintentos y la antigüedad en cola por endpoint y remitente. Consulte Prácticas recomendadas para la WhatsApp Messages API para la gestión de colas, conciliación y prevención de duplicados.