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):
| Regla | Valor |
|---|---|
| Ritmo constante hacia un destinatario | 1 mensaje cada 6 segundos (0,17 mensajes/s) |
| Equivalente | unos 10 mensajes por minuto, 600 por hora |
| Ráfaga permitida | hasta 45 mensajes en 6 segundos, tomados de la cuota futura |
| Después de una ráfaga | espera lo que habrían tardado esos mensajes al ritmo normal: una ráfaga de 20 requiere unos 2 minutos |
| Reintento recomendado por Meta | despué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-Deliveryo con elwamid.
¿Dónde lo ves en Genuka WA?
| Canal | Qué recibes |
|---|---|
Respuesta de POST /api/v1/messages | 400, "error": "send_retryable", meta.code: 131056, meta.retryable: true |
| Campaña | El destinatario se reintenta y luego pasa a failed si fallan los tres intentos |
| Panel, sección Registros | La 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 01y237690000001son 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
Error 131048 de WhatsApp: envíos restringidos — causa y solución
Error 131048 de WhatsApp: Meta restringe los envíos del número tras bloqueos o reportes de spam. Cómo leer la calificación de calidad y hacer que vuelva a subir.
Error 368 de WhatsApp: cuenta restringida — causa y solución
Error 368 de WhatsApp: la cuenta de WhatsApp Business está restringida o desactivada por una infracción de las políticas de Meta. Duraciones, solicitud de revisión y prevención.