Erreur WhatsApp 131056 : limite par destinataire

L'erreur WhatsApp 131056 signifie que vous avez envoyé trop de messages au même destinataire en trop peu de temps : Meta autorise en régime normal un message toutes les 6 secondes par paire expéditeur-destinataire. Attendez avant de réécrire à cette personne ; vos envois vers d'autres numéros, eux, peuvent continuer sans pause.

Que signifie l'erreur 131056 ?

« Too many messages sent from the sender phone number to the same recipient phone number in a short period of time. » — Meta, codes d'erreur de la Cloud API

Meta conseille d'attendre puis de réessayer si vous tenez à écrire à ce numéro, et rappelle que vous pouvez écrire à un autre numéro sans attendre. La règle derrière ce code est la limite par paire (pair rate limit) (Meta, About the platform) :

Quand l'erreur 131056 apparaît-elle ?

• Un doublon dans une liste de campagne. Genuka WA ne dédoublonne pas les destinataires d'une campagne : le même numéro présent deux fois reçoit deux envois consécutifs.
• Un bot qui découpe sa réponse en cinq ou six bulles envoyées d'affilée.
• Un bouton « Renvoyer le code » sans délai minimal entre deux clics.
• Un traitement de webhook non idempotent qui répond à chaque relivraison du même message entrant. Les webhooks Genuka WA peuvent arriver en double : dédoublonnez sur X-Genuka-Delivery ou sur le wamid.

Où la voir dans Genuka WA ?

Un détail compte pour les campagnes : les trois tentatives du lanceur s'enchaînent en moins de deux secondes (attentes de 500 ms puis 1 s au plus), moins que les 6 secondes de la limite par paire. Un doublon dans la liste finit donc généralement en failed. La correction est de dédoublonner en amont, pas d'allonger les tentatives.

Comment corriger l'erreur 131056 ?

const API = "https://wa.genuka.com/api/v1";
const PAIR_GAP_MS = 6_000;
const lastSentTo = new Map<string, number>(); // à déplacer dans Redis si vous avez plusieurs 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. Respecter l'écart minimal vers ce destinataire.
  const wait = (lastSentTo.get(payload.to) ?? 0) + PAIR_GAP_MS - Date.now();
  if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));

  // 2. Sur 131056, réessayer après 4^X secondes : 1 s, 4 s, 16 s, 64 s, soit cinq tentatives.
  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; // pas d'attente après la dernière tentative
    await new Promise((resolve) => setTimeout(resolve, 4 ** x * 1_000));
  }
  throw new Error("131056: destinataire toujours limité, à replanifier");
}

Comment éviter l'erreur 131056 ?

• Dédoublonnez vos listes avant POST /api/v1/campaigns, sur le numéro normalisé (chiffres seuls, avec indicatif) : +237 690 00 00 01 et 237690000001 sont le même destinataire.
• Regroupez vos bulles. Un message de 4 096 caractères au plus vaut mieux que cinq messages courts envoyés d'affilée.
• Mettez un délai minimal sur les renvois de code, 30 à 60 secondes, ce qui protège aussi vos utilisateurs contre les abus.
• Rendez le traitement des webhooks idempotent, pour qu'une relivraison ne déclenche jamais une seconde réponse.

Quels codes sont liés ?

• 130429 : le débit global du numéro est atteint, tous destinataires confondus.
• 131048 : envois restreints pour cause de signalements ; insister vers un même destinataire n'aide pas.

FAQ

L'erreur 131056 bloque-t-elle mes envois vers les autres clients ?

Non. Meta le précise : vous pouvez continuer à écrire à d'autres numéros sans attendre. Seule la paire expéditeur-destinataire concernée est freinée.

Combien de messages puis-je envoyer à un même client par heure ?

En régime continu, environ 600, soit un toutes les 6 secondes. Une rafale de 45 messages en 6 secondes est tolérée, mais elle se paie ensuite par une attente équivalente.

Faut-il un délai fixe ou croissant pour réessayer ?

Croissant. Meta recommande 4^X secondes, X partant de 0 : 1 s, 4 s, 16 s, 64 s. Un délai fixe court renvoie la requête alors que la limite est toujours active.

Sources

• Meta — Error codes
• Meta — About the platform, pair rate limits
• Meta — Throughput