Genuka WA docs

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):

RegolaValore
Ritmo costante verso un destinatario1 messaggio ogni 6 secondi (0,17 messaggi/s)
Equivalentecirca 10 messaggi al minuto, 600 all'ora
Raffica consentitafino a 45 messaggi in 6 secondi, presi in prestito dalla quota futura
Dopo una rafficaaspetta quanto avrebbero richiesto quei messaggi al ritmo normale: una raffica di 20 richiede circa 2 minuti
Nuovo tentativo consigliato da Metadopo 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?

CanaleCosa ottieni
Risposta di POST /api/v1/messages400, "error": "send_retryable", meta.code: 131056, meta.retryable: true
CampagnaIl destinatario viene riprovato, poi diventa failed se falliscono tutti e tre i tentativi
Dashboard, sezione LogLa 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 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: è 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

In questa pagina