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

URL: https://wa.genuka.com/es/docs/errors/131056
Language: Spanish

> 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#throttling-errors)

(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](https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform#rate-limits)):

| 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-Delivery` o con el `wamid`.

### ¿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?

1. **Deja de escribirle a ese destinatario por ahora** y continúa normalmente con los demás.
2. **Reintenta según el calendario de Meta**: 1 s, luego 4 s, luego 16 s, luego 64 s.
3. **Espacia los envíos por destinatario**: una cola por número, con al menos 6 segundos entre dos
   mensajes.

**Node.js**

```ts
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");
}
```

**Python**

```python
import os
import time

import requests

API = "https://wa.genuka.com/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['GENUKA_WA_API_KEY']}",
    "User-Agent": "acme-crm/1.0 (+https://example.com)",
}
PAIR_GAP = 6.0
last_sent_to: dict[str, float] = {}  # pásalo a Redis si ejecutas varios procesos


def send_to_recipient(payload: dict) -> dict:
    wait = last_sent_to.get(payload["to"], 0) + PAIR_GAP - time.time()
    if wait > 0:
        time.sleep(wait)

    for x in range(5):  # cinco intentos, con 1 s, 4 s, 16 s, 64 s entre ellos
        response = requests.post(f"{API}/messages", json=payload, headers=HEADERS, timeout=30)
        last_sent_to[payload["to"]] = time.time()
        body = response.json()
        if response.ok:
            return body["data"]
        if body.get("meta", {}).get("code") != 131056:
            raise RuntimeError(f"{body.get('error')}: {body.get('message', '')}")
        if x == 4:
            break  # sin espera después del último intento
        time.sleep(4 ** x)
    raise RuntimeError("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](https://wa.genuka.com/es/docs/errors/130429): se alcanzó la capacidad de envío **global** del número, sumando
  todos los destinatarios.
* [131048](https://wa.genuka.com/es/docs/errors/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

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — About the platform, pair rate limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform#rate-limits)
* [Meta — Throughput](https://developers.facebook.com/documentation/business-messaging/whatsapp/throughput)
