Errore WhatsApp 131056: limite per coppia — causa e soluzione
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
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):
| 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-Deliveryo sulwamid.
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?
Smetti di scrivere a quel destinatario per ora, e continua normalmente con gli altri.
Riprova secondo la scansione di Meta: 1 s, poi 4 s, poi 16 s, poi 64 s.
Distanzia gli invii per destinatario: una coda per numero, con almeno 6 secondi tra due messaggi.
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");
}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 01e237690000001sono 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: è stato raggiunto il throughput complessivo del numero, su tutti i destinatari.
- 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
Errore WhatsApp 131048: invii limitati — causa e soluzione
Errore WhatsApp 131048: Meta limita gli invii del numero dopo blocchi o segnalazioni di spam. Come leggere la valutazione di qualità e farla risalire.
Errore WhatsApp 368: account limitato — causa e soluzione
Errore WhatsApp 368: il WhatsApp Business Account è limitato o disattivato per una violazione delle policy di Meta. Durate, richiesta di revisione, prevenzione.