Rendimiento y límites de tasa de la API Cloud de WhatsApp

¿Qué códigos de error aparecen al llegar a un límite?

Relacione el código con el límite y elija después la respuesta.

Los códigos 131048 y 131049 tienen que ver con la calidad y la interacción más que con la velocidad, así que reintentar más rápido no ayudará. Véase la resolución de problemas de códigos de error de la API de WhatsApp.

En la API de OmniChannels.ai, un rechazo del proveedor llega como HTTP 502 con el código de error y el texto de Meta en message, y nuestra propia limitación de tasa devuelve 429 con una cabecera Retry-After. Véanse errores y límites para la tabla completa y los límites por defecto.

¿Cómo debo poner en cola y reintentar?

Ponga una cola entre su aplicación y la API, limite el ritmo por debajo de su tope y reintente solo lo que pueda salir bien más adelante.

1. Ponga en cola cada envío. Su aplicación escribe los mensajes en una cola y un grupo de workers la vacía. No recorra nunca una lista de clientes dentro de un único gestor de solicitudes.
2. Limite el ritmo con un token bucket fijado por debajo de su rendimiento, dejando margen para las respuestas y para el resto del tráfico que comparte el mismo tope.
3. Registre primero cada intento. Escriba una fila por mensaje con su propio ID de operación como clave, guarde el ID de mensaje devuelto y omita todo lo que ya se haya aceptado.
4. Reintente los fallos transitorios. Se reintentan las limitaciones y los errores temporales del servidor; los errores de validación (400), de autenticación y de plantilla no.
5. Aplique backoff con jitter. Espere más tras cada intento, añada aleatoriedad para que los workers no reintenten a la vez y ponga un tope al retraso y al número de intentos.
6. Respete Retry-After cuando la respuesta lo incluya.
7. Compruebe antes de reenviar tras un tiempo de espera agotado. Perder la respuesta no significa perder el mensaje; consulte primero los eventos de estado.

const RETRYABLE = new Set([429, 500, 502, 503, 504]);

async function sendWithBackoff(send, { maxAttempts = 5, baseMs = 500, capMs = 30000 } = {}) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await send();
    if (res.ok) return res;
    if (!RETRYABLE.has(res.status) || attempt === maxAttempts) throw new Error(`failed: ${res.status}`);
    const wait = Math.random() * Math.min(capMs, baseMs * 2 ** (attempt - 1)); // full jitter
    await new Promise((r) => setTimeout(r, wait));
  }
}

La página de Meta sobre rendimiento no da ninguna regla de backoff para el error 130429, así que esto es práctica de ingeniería habitual. Un 502 que lleve un código de limitación de Meta debe tratarse como reintentable; para cualquier otro código del proveedor, lea antes el mensaje. Nuestra página de errores y límites incluye la tabla completa de reintentos y la protección frente a envíos duplicados.

¿Cómo planifico un envío grande?

Calcule el tiempo, los límites y la carga de webhooks antes de empezar.

1. Cuente los destinatarios únicos y compárelos con su límite de mensajes. Empiece por el plan de escalado seguro si la lista supera su nivel.
2. Estime la duración. Los mensajes divididos entre su rendimiento dan segundos. Como cálculo, 100.000 mensajes a 80 por segundo tardan 1.250 segundos, unos 21 minutos, si nada más usa el tope.
3. Reserve capacidad. El tope también cuenta los mensajes entrantes, así que deje margen para las respuestas de los clientes durante el envío.
4. Dimensione su servidor de webhooks. Meta indica que los servidores de webhooks deben poder gestionar el triple de su tráfico de mensajes salientes más el tráfico entrante previsto, con una latencia mediana que no supere los 250 ms y menos del 1 % de las solicitudes por encima de 1 segundo. Véase la guía de webhooks.
5. Revise antes la salud de las plantillas y la calidad, y escalone el envío en lotes para poder detenerlo si aumentan los fallos o los bloqueos. Véase envío masivo sin que le bloqueen.
6. Use ID de medio en lugar de enlaces al enviar archivos en volumen, como aconseja Meta. Véanse tipos de archivo y límites.

En OmniChannels.ai, los puntos de conexión masivos aceptan muchos destinatarios en una sola solicitud y un campo delay permite espaciar la entrega. Acuerde con nuestro equipo los planes para los picos con antelación.

Ejemplo práctico: una venta flash en Dubái

«Marina Gadgets» (sintética) planea una plantilla de venta flash para 60.000 clientes con consentimiento.

1. Su límite lo permite, así que el volumen no es la restricción; lo es la velocidad. A 80 mps, 60.000 mensajes necesitan 750 segundos.
2. Envían en seis lotes de 10.000 con un limitador de ritmo a 60 mps, lo que deja margen para las respuestas.
3. Un lote muestra varios errores 131056 en clientes que también recibieron una actualización de pedido ese mismo minuto. Retrasan esos envíos unos minutos.
4. Un worker reintenta las solicitudes limitadas con backoff y jitter, y ningún mensaje se reintenta una vez que tiene un ID.
5. El punto de conexión del webhook guarda los eventos y devuelve 200, y después un worker actualiza los estados.
6. Tras cada lote revisan los fallos y la calidad de las plantillas antes de continuar.

¿Cuáles son los errores más comunes?

• Confundir los límites. El rendimiento, el límite por par, los límites de Graph API y los límites de mensajes son problemas distintos.
• Reintentar de inmediato, lo que mantiene el número en el tope y prolonga el problema.
• Enviar justo en el tope, de modo que las respuestas y los estados compiten con la campaña.
• Reenviar tras un tiempo de espera agotado sin comprobar el estado, lo que duplica los mensajes.
• Consultar en bucle los puntos de conexión de Graph API y alcanzar el límite por hora.
• Servidores de webhooks infradimensionados que se retrasan y provocan reintentos.
• Los límites cambian. Esta guía recoge los valores de Meta en el momento de redactar este texto.

Cómo le ayuda OmniChannels.ai

BroadNet es un Business Solution Provider oficial de Meta, y OmniChannels.ai envía WhatsApp mediante una sola API con puntos de conexión masivos, un campo delay para espaciar el envío, programación y estados de entrega en un único formato de webhook normalizado. Los revendedores disponen de webhooks y crédito independientes por subcuenta. Planifique los picos con nuestro equipo y consulte la documentación de la API de WhatsApp, los errores y límites y la página de campañas.