Genuka WA docs

Error 131056 de WhatsApp: límite por par — causa y solución

Error 131056 de WhatsApp: demasiados mensajes al mismo destinatario en poco tiempo. El límite de velocidad por par de Meta (1 mensaje cada 6 s) y cómo reintentarlo correctamente.

El error 131056 de WhatsApp significa que enviaste demasiados mensajes al mismo destinatario en muy poco tiempo: a ritmo constante, Meta permite un mensaje cada 6 segundos por par remitente-destinatario. Espera antes de volver a escribirle a esa persona; tus envíos a otros números pueden continuar sin ninguna pausa.

¿Qué significa el error 131056?

"Too many messages sent from the sender phone number to the same recipient phone number in a short period of time." — Meta, códigos de error de la Cloud API

(Se enviaron demasiados mensajes desde el número de teléfono remitente al mismo número de teléfono destinatario en un periodo corto).

Meta aconseja esperar y reintentar si quieres escribirle a ese número, y recuerda que puedes escribirle a un número distinto sin esperar. La regla detrás de este código es el límite de velocidad por par (Meta, About the platform):

ReglaValor
Ritmo constante hacia un destinatario1 mensaje cada 6 segundos (0,17 mensajes/s)
Equivalenteunos 10 mensajes por minuto, 600 por hora
Ráfaga permitidahasta 45 mensajes en 6 segundos, tomados de la cuota futura
Después de una ráfagaespera lo que habrían tardado esos mensajes al ritmo normal: una ráfaga de 20 requiere unos 2 minutos
Reintento recomendado por Metadespués de 4^X segundos, con X empezando en 0 y aumentando en 1 tras cada fallo

¿Cuándo aparece el error 131056?

  • Un duplicado en la lista de una campaña. Genuka WA no elimina los duplicados de los destinatarios de una campaña: el mismo número listado dos veces recibe dos envíos seguidos.
  • Un bot que divide su respuesta en cinco o seis burbujas enviadas una tras otra.
  • Un botón "Reenviar código" sin un tiempo mínimo entre dos pulsaciones.
  • Un manejador de webhooks no idempotente que responde a cada reentrega del mismo mensaje entrante. Los webhooks de Genuka WA pueden llegar dos veces: elimina los duplicados con X-Genuka-Delivery o con el wamid.

¿Dónde lo ves en Genuka WA?

CanalQué recibes
Respuesta de POST /api/v1/messages400, "error": "send_retryable", meta.code: 131056, meta.retryable: true
CampañaEl destinatario se reintenta y luego pasa a failed si fallan los tres intentos
Panel, sección RegistrosLa solicitud rechazada y el cuerpo de la respuesta

Un detalle importa en las campañas: los tres intentos del lanzador se suceden en menos de dos segundos (esperas de 500 ms como máximo, luego 1 s), menos que los 6 segundos del límite por par. Por eso un duplicado en la lista suele terminar en failed. La solución es eliminar los duplicados antes, no alargar los reintentos.

¿Cómo corrijo el error 131056?

Deja de escribirle a ese destinatario por ahora y continúa normalmente con los demás.

Reintenta según el calendario de Meta: 1 s, luego 4 s, luego 16 s, luego 64 s.

Espacia los envíos por destinatario: una cola por número, con al menos 6 segundos entre dos mensajes.

const API = "https://wa.genuka.com/api/v1";
const PAIR_GAP_MS = 6_000;
const lastSentTo = new Map<string, number>(); // pásalo a Redis si ejecutas varios procesos

async function send(payload: { connectionId: string; to: string } & Record<string, unknown>) {
  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),
  });
  return { response, json: await response.json() };
}

export async function sendToRecipient(payload: { connectionId: string; to: string } & Record<string, unknown>) {
  // 1. Respeta el intervalo mínimo hacia este destinatario.
  const wait = (lastSentTo.get(payload.to) ?? 0) + PAIR_GAP_MS - Date.now();
  if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));

  // 2. Ante un 131056, reintenta después de 4^X segundos: 1 s, 4 s, 16 s, 64 s, es decir, cinco intentos en total.
  for (let x = 0; x <= 4; x++) {
    const { response, json } = await send(payload);
    lastSentTo.set(payload.to, Date.now());
    if (response.ok) return json.data;
    if (json.meta?.code !== 131056) throw new Error(`${json.error}: ${json.message ?? ""}`);
    if (x === 4) break; // sin espera después del último intento
    await new Promise((resolve) => setTimeout(resolve, 4 ** x * 1_000));
  }
  throw new Error("131056: destinatario aún limitado, reprogramar");
}

¿Cómo evito el error 131056?

  • Elimina los duplicados de tus listas antes de POST /api/v1/campaigns, sobre el número normalizado (solo dígitos, con código de país): +237 690 00 00 01 y 237690000001 son el mismo destinatario.
  • Agrupa tus burbujas. Un mensaje de hasta 4.096 caracteres es mejor que cinco cortos enviados uno tras otro.
  • Pon un tiempo mínimo al reenvío de códigos, de 30 a 60 segundos, lo que además protege a tus usuarios contra abusos.
  • Haz que el manejo de webhooks sea idempotente, para que una reentrega nunca provoque una segunda respuesta.

Códigos de error relacionados

  • 130429: se alcanzó la capacidad de envío global del número, sumando todos los destinatarios.
  • 131048: envíos restringidos por reportes de spam; insistir con un destinatario no ayuda.

Preguntas frecuentes

¿El error 131056 bloquea mis envíos a otros clientes?

No. Meta lo dice: puedes seguir escribiendo a otros números sin esperar. Solo se frena el par remitente-destinatario afectado.

¿Cuántos mensajes puedo enviarle a un cliente por hora?

A ritmo constante, unos 600, uno cada 6 segundos. Se tolera una ráfaga de 45 mensajes en 6 segundos, pero la pagas después con una espera equivalente.

¿Debo reintentar con una espera fija o creciente?

Creciente. Meta recomienda 4^X segundos, con X empezando en 0: 1 s, 4 s, 16 s, 64 s. Una espera fija y corta vuelve a enviar la solicitud mientras el límite sigue vigente.

Fuentes

En esta página