Genuka WA docs

Error 130429 de WhatsApp: Rate limit hit — causa y solución

El error 130429 de WhatsApp (Rate limit hit) significa que tu número superó su capacidad de envío en la Cloud API. Los límites por número y cómo reintentar sin perder mensajes.

El error 130429 de WhatsApp significa que tu número superó su capacidad de envío en la Cloud API de Meta: 80 mensajes por segundo de forma predeterminada, 20 para un número en coexistencia con la aplicación WhatsApp Business. No hay nada roto. Reduce el ritmo, reintenta con una espera creciente y distribuye los envíos grandes en el tiempo en lugar de lanzarlos todos a la vez.

¿Qué significa el error 130429?

Meta lo clasifica entre los errores de límite de velocidad:

"Cloud API message throughput has been reached." — Meta, códigos de error de la Cloud API

Dicho de otro modo, el número agotó la cantidad de mensajes por segundo que tiene permitida. En la respuesta de Graph, el campo message combina el código y su título: (#130429) Rate limit hit. Meta advierte que estos títulos dejarán de usarse en algún momento, así que basa tu gestión en el código, nunca en el texto.

La capacidad de envío se cuenta por número e incluye los mensajes entrantes y salientes de todos los tipos (Meta, Throughput):

NúmeroCapacidad máxima
Número estándar de la Cloud API80 mensajes/s
Número mejorado automáticamente por Metahasta 1.000 mensajes/s
Número en coexistencia (también usado en la aplicación WhatsApp Business)20 mensajes/s, fijo

Meta sigue devolviendo 130429 hasta que vuelvas a estar por debajo de ese techo.

¿Cuándo aparece el error 130429?

  • Un bucle de envío sin control de ritmo: un script que recorre una lista de 10.000 contactos tan rápido como lo permite la red supera los 80 mensajes/s en cuestión de instantes.
  • Un número en coexistencia: el tope de 20 mensajes/s se aplica sea cual sea tu nivel. Una campaña de 100.000 destinatarios tarda en él al menos 83 minutos.
  • Varios emisores en un mismo número: dos procesos, dos campañas o un flujo de llamadas a la API que corre junto a una campaña comparten la misma capacidad sin coordinarse.
  • Un pico de mensajes entrantes: cuentan contra la misma capacidad que tus envíos.

No confundas el 130429 con otros dos techos:

TechoQué cuentaCódigo
Capacidad de envíoMensajes por segundo, por número130429
Límite por parMensajes al mismo destinatario131056
Límite de mensajesDestinatarios únicos fuera de la ventana de servicio en 24 h móviles, a nivel del portafolio comercialconsulta Meta, Messaging limits

¿Dónde lo ves en Genuka WA?

CanalQué recibes
Respuesta de POST /api/v1/messages400, "error": "send_retryable", meta.code: 130429, meta.retryable: true
CampañaCada destinatario se reintenta; solo pasa a failed después de tres intentos
Panel, sección RegistrosLa solicitud rechazada, con el cuerpo de la respuesta
400 — respuesta de POST /api/v1/messages
{
  "error": "send_retryable",
  "message": "Cloud API message throughput has been reached.",
  "meta": {
    "errorClass": "retryable",
    "retryable": true,
    "code": 130429,
    "details": "Cloud API message throughput has been reached.",
    "traceId": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

El estado HTTP es 400, no 429: decide si reintentar a partir de meta.retryable, no del estado.

¿Cómo corrijo el error 130429?

Reintenta con una espera creciente. Genuka WA nunca reintenta por ti un envío individual hecho con POST /api/v1/messages: una solicitud interactiva no debería tardar varios segundos en fallar en silencio. Tu código reintenta, con una espera que se duplica en cada intento más un poco de variación aleatoria (jitter) para que tus procesos no se reinicien todos en el mismo milisegundo.

Mide tu techo real. GET /api/v1/numbers devuelve, para cada número, un campo messagesPerSecond (20, 80 o 1.000) y coexistence: true cuando el número también se usa en la aplicación. Ajusta el ritmo de tus envíos a ese valor, no a un valor predeterminado de 80.

Haz los envíos masivos con una campaña. POST /api/v1/campaigns y luego /api/v1/campaigns/{id}/launch: Genuka WA ajusta el ritmo a la capacidad del número y hace hasta tres intentos por destinatario (esperas de 500 ms como máximo, luego 1 s, con variación aleatoria). Un 130429 puntual no te hace perder al destinatario. Consulta la guía de la API de campañas.

const API = "https://wa.genuka.com/api/v1";

export async function sendWithBackoff(payload: unknown, maxAttempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(`${API}/messages`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    });
    // Un 5xx puede llegar como texto plano ("error code: 502" del proxy): el JSON no está garantizado.
    const json = await response.json().catch(() => null);
    if (response.ok) return json?.data; // { messageId, warning? }

    // meta.retryable es true para los límites de velocidad (130429, 131056, 4, 80007), los errores
    // internos de Meta (131000, 5xx), los medios caducados y el 131048. Este último se reintenta más
    // tarde, no en este bucle (consulta la página del 131048). Un 5xx sin `meta` no indica si el
    // mensaje salió: se lanza tal cual, verifica antes de reenviar para evitar un duplicado.
    const retryable = json?.meta?.retryable === true && json.meta.code !== 131048;
    if (!retryable || attempt >= maxAttempts) {
      throw new Error(`${response.status} ${json?.error ?? ""}: ${json?.message ?? ""}`);
    }
    const base = Math.min(30_000, 1_000 * 2 ** (attempt - 1));
    await new Promise((resolve) => setTimeout(resolve, base / 2 + Math.random() * (base / 2)));
  }
}

¿Cómo evito el error 130429?

  • Un solo emisor por número. Pasa todos los envíos de un número por una única cola, con un ritmo por debajo de messagesPerSecond. Eso es lo que evita que dos procesos se pisen.
  • Planifica la duración de los envíos grandes. A 20 mensajes/s, un número en coexistencia envía como máximo 72.000 mensajes por hora. Anuncia la duración en lugar de descubrirla.
  • Usa medios alojados por Meta para los envíos rápidos: Meta recomienda enviar un ID de medio en lugar de una URL en tus propios servidores para aprovechar una mayor capacidad de envío (Meta, Throughput). Con Genuka WA, assetId hace exactamente eso.
  • No reintentes a intervalos fijos. Un bucle de "tres intentos, con un segundo de diferencia" envía la misma ráfaga en el mismo momento y recibe otro 130429.

Códigos de error relacionados

  • 131056: demasiados mensajes al mismo destinatario en poco tiempo.
  • 131048: envíos restringidos tras bloqueos o reportes de spam, un problema de calidad más que de velocidad.
  • 4 y 80007: los otros dos límites de la misma familia, que cuentan llamadas a la API de la aplicación y de la cuenta de WhatsApp Business, no mensajes enviados.

Preguntas frecuentes

¿Mi número puede llegar a 1.000 mensajes por segundo?

Sí, de forma automática y sin costo, cuando se cumplen tres condiciones: un límite de mensajes ilimitado, al menos 100.000 usuarios únicos contactados fuera de una ventana de servicio en 24 horas móviles, y una calificación de calidad de al menos media. Durante la mejora, que tarda hasta un minuto, el número responde 131057 (Meta, Throughput). Un número en coexistencia se queda en 20 mensajes/s.

¿Meta cobra un mensaje rechazado con 130429?

No. Meta solo cobra un mensaje de plantilla cuando se entrega (Meta, Pricing), y un mensaje rechazado con 130429 nunca salió. Del lado de Genuka WA, un envío rechazado tampoco consume la cuota de tu suscripción: solo se cuentan los mensajes que Meta aceptó.

¿Por qué Genuka WA responde 400 y no 429?

Porque todos los rechazos de Meta en un envío vuelven como 400, salvo los problemas de token, de permisos y de registro del número, que vuelven como 409. Si conviene reintentar lo indican meta.retryable y meta.errorClass, que existen para eso.

¿El 130429 puede venir de la propia API de Genuka WA?

No. El 130429 es un código de Meta que Genuka WA transmite tal cual en meta.code: siempre se refiere a la capacidad de envío del número emisor en Meta, no a tu clave API.

Fuentes

En esta página