# Errore WhatsApp 131056: limite per coppia — causa e soluzione

URL: https://wa.genuka.com/it/docs/errors/131056
Language: Italian

> Errore WhatsApp 131056: troppi messaggi allo stesso destinatario in poco tempo. Il limite di frequenza per coppia di Meta (1 messaggio ogni 6 s) e come riprovare nel modo giusto.

L'errore WhatsApp 131056 significa che hai inviato troppi messaggi allo stesso destinatario in troppo poco tempo:
a ritmo costante, Meta consente un messaggio ogni 6 secondi per coppia mittente-destinatario. Aspetta prima di
scrivere di nuovo a quella persona; i tuoi invii verso altri numeri possono proseguire senza alcuna pausa.

## Cosa significa l'errore 131056?

> "Too many messages sent from the sender phone number to the same recipient phone number in a
> short period of time."
> — [Meta, Cloud API error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#throttling-errors)

Meta consiglia di aspettare e riprovare se intendi scrivere a quel numero, e ti ricorda che puoi
scrivere a un numero **diverso** senza aspettare. La regola dietro questo codice è il **limite di frequenza
per coppia**
([Meta, About the platform](https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform#rate-limits)):

| Regola                               | Valore                                                                                                       |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| Ritmo costante verso un destinatario | 1 messaggio ogni 6 secondi (0,17 messaggi/s)                                                                 |
| Equivalente                          | circa 10 messaggi al minuto, 600 all'ora                                                                     |
| Raffica consentita                   | fino a 45 messaggi in 6 secondi, presi in prestito dalla quota futura                                        |
| Dopo una raffica                     | aspetta quanto avrebbero richiesto quei messaggi al ritmo normale: una raffica di 20 richiede circa 2 minuti |
| Nuovo tentativo consigliato da Meta  | dopo 4^X secondi, con X che parte da 0 e cresce di 1 dopo ogni fallimento                                    |

## Quando si verifica l'errore 131056?

* **Un duplicato in una lista di campagna.** Genuka WA non deduplica i destinatari di una campagna: lo
  stesso numero presente due volte riceve due invii uno dopo l'altro.
* **Un bot che spezza la sua risposta** in cinque o sei bolle inviate di fila.
* **Un pulsante "Reinvia codice"** senza un ritardo minimo tra due tocchi.
* **Un gestore di webhook non idempotente** che risponde a ogni riconsegna dello stesso messaggio
  in entrata. I webhook di Genuka WA possono arrivare due volte: deduplica su `X-Genuka-Delivery` o sul
  `wamid`.

### Dove lo vedi in Genuka WA?

| Canale                              | Cosa ottieni                                                                                |
| ----------------------------------- | ------------------------------------------------------------------------------------------- |
| Risposta di `POST /api/v1/messages` | `400`, `"error": "send_retryable"`, `meta.code: 131056`, `meta.retryable: true`             |
| Campagna                            | Il destinatario viene riprovato, poi diventa `failed` se falliscono tutti e tre i tentativi |
| Dashboard, sezione Log              | La richiesta rifiutata e il corpo della risposta                                            |

Un dettaglio conta per le campagne: i tre tentativi del launcher si susseguono in meno di due
secondi (attese di al massimo 500 ms, poi 1 s), meno dei 6 secondi del limite per coppia. Un
duplicato nella lista finisce quindi di solito `failed`. La soluzione è deduplicare a monte, non
allungare i tentativi.

## Come risolvo l'errore 131056?

1. **Smetti di scrivere a quel destinatario per ora**, e continua normalmente con gli altri.
2. **Riprova secondo la scansione di Meta**: 1 s, poi 4 s, poi 16 s, poi 64 s.
3. **Distanzia gli invii per destinatario**: una coda per numero, con almeno 6 secondi tra due
   messaggi.

**Node.js**

```ts
const API = "https://wa.genuka.com/api/v1";
const PAIR_GAP_MS = 6_000;
const lastSentTo = new Map<string, number>(); // move this to Redis if you run several workers

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. Respect the minimum gap to this recipient.
  const wait = (lastSentTo.get(payload.to) ?? 0) + PAIR_GAP_MS - Date.now();
  if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));

  // 2. On 131056, retry after 4^X seconds: 1 s, 4 s, 16 s, 64 s, so five attempts in all.
  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; // no wait after the last attempt
    await new Promise((resolve) => setTimeout(resolve, 4 ** x * 1_000));
  }
  throw new Error("131056: recipient still rate-limited, reschedule");
}
```

**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] = {}  # move this to Redis if you run several workers


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):  # five attempts, with 1 s, 4 s, 16 s, 64 s between them
        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  # no wait after the last attempt
        time.sleep(4 ** x)
    raise RuntimeError("131056: recipient still rate-limited, reschedule")
```

## Come prevengo l'errore 131056?

* **Deduplica le tue liste prima di `POST /api/v1/campaigns`**, sul numero normalizzato (solo cifre,
  con prefisso internazionale): `+237 690 00 00 01` e `237690000001` sono lo stesso destinatario.
* **Raggruppa le tue bolle.** Un messaggio fino a 4.096 caratteri è meglio di cinque brevi inviati di
  fila.
* **Metti un ritardo minimo sui rinvii del codice**, da 30 a 60 secondi, che protegge anche i tuoi utenti dagli
  abusi.
* **Rendi idempotente la gestione dei webhook**, così una riconsegna non provoca mai una seconda risposta.

## Codici di errore correlati

* [130429](https://wa.genuka.com/it/docs/errors/130429): è stato raggiunto il throughput **complessivo** del numero, su tutti i
  destinatari.
* [131048](https://wa.genuka.com/it/docs/errors/131048): invii limitati a causa di segnalazioni di spam; insistere su un
  destinatario non aiuta.

## FAQ

### L'errore 131056 blocca i miei invii verso altri clienti?

No. Lo dice Meta: puoi continuare a scrivere ad altri numeri senza aspettare. Viene rallentata solo la coppia
mittente-destinatario interessata.

### Quanti messaggi posso inviare a un cliente all'ora?

A ritmo costante, circa 600, uno ogni 6 secondi. Una raffica di 45 messaggi in 6 secondi è
tollerata, ma la paghi dopo con un'attesa equivalente.

### Devo riprovare con un ritardo fisso o crescente?

Crescente. Meta consiglia 4^X secondi, con X che parte da 0: 1 s, 4 s, 16 s, 64 s. Un ritardo fisso breve
rinvia la richiesta mentre il limite è ancora in vigore.

## Fonti

* [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)
