Erreur WhatsApp 130429 : Rate limit hit, cause et solution

L'erreur WhatsApp 130429 signifie que votre numéro a dépassé son débit d'envoi sur la Cloud API de Meta : 80 messages par seconde par défaut, 20 pour un numéro en coexistence avec l'application WhatsApp Business. Rien n'est cassé. Ralentissez, réessayez avec un délai croissant, et répartissez les gros envois dans le temps.

Que signifie l'erreur 130429 ?

Meta la range parmi les erreurs de limitation de débit (throttling errors) :

« Cloud API message throughput has been reached. » — Meta, codes d'erreur de la Cloud API

Autrement dit, le débit de messages autorisé pour ce numéro est atteint. Dans la réponse de Graph, le champ message combine le code et son titre : (#130429) Rate limit hit. Meta prévient que ces titres disparaîtront à terme : construisez votre logique sur le code, jamais sur le texte.

Le débit se compte par numéro et inclut les messages entrants comme sortants, tous types confondus (Meta, Throughput) :

Meta renvoie 130429 tant que vous restez au-dessus de ce plafond.

Quand l'erreur 130429 apparaît-elle ?

• Une boucle d'envoi sans rythme : un script qui parcourt une liste de 10 000 contacts aussi vite que le réseau le permet dépasse 80 messages/s en quelques instants.
• Un numéro en coexistence : le plafond de 20 messages/s s'applique quel que soit votre palier. Une campagne de 100 000 destinataires y prend au minimum 83 minutes.
• Plusieurs émetteurs sur le même numéro : deux workers, deux campagnes, ou un flux d'appels API en parallèle d'une campagne se partagent le même débit sans se concerter.
• Un pic de messages entrants : ils comptent dans le même débit que vos envois.

Ne confondez pas 130429 avec deux autres plafonds :

Où la voir dans Genuka WA ?

{
  "error": "send_retryable",
  "message": "Cloud API message throughput has been reached.",
  "meta": {
    "errorClass": "retryable",
    "retryable": true,
    "code": 130429,
    "details": "Cloud API message throughput has been reached.",
    "traceId": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

Le statut HTTP est un 400 et non un 429 : décidez de réessayer d'après meta.retryable, pas d'après le statut.

Comment corriger l'erreur 130429 ?

const API = "https://wa.genuka.com/api/v1";

export async function sendWithBackoff(payload: unknown, maxAttempts = 5) {
  for (let attempt = 1; ; attempt++) {
    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),
    });
    // Un 5xx peut arriver en texte brut (« error code: 502 » du proxy) : pas de JSON garanti.
    const json = await response.json().catch(() => null);
    if (response.ok) return json?.data; // { messageId, warning? }

    // meta.retryable est vrai pour les limites de débit (130429, 131056, 4, 80007), les erreurs
    // internes de Meta (131000, 5xx), les médias périmés et 131048. Ce dernier se réessaie plus
    // tard, pas dans cette boucle (voir la page 131048). Un 5xx sans `meta` ne dit pas si le
    // message est parti : il remonte tel quel, vérifiez avant de renvoyer pour éviter un doublon.
    const retryable = json?.meta?.retryable === true && json.meta.code !== 131048;
    if (!retryable || attempt >= maxAttempts) {
      throw new Error(`${response.status} ${json?.error ?? ""}: ${json?.message ?? ""}`);
    }
    const base = Math.min(30_000, 1_000 * 2 ** (attempt - 1));
    await new Promise((resolve) => setTimeout(resolve, base / 2 + Math.random() * (base / 2)));
  }
}

Comment éviter l'erreur 130429 ?

• Un seul émetteur par numéro. Faites passer tous les envois d'un numéro par une même file d'attente, cadencée sous messagesPerSecond. C'est ce qui évite que deux processus se marchent dessus.
• Prévoyez la durée des gros envois. À 20 messages/s, un numéro en coexistence envoie 72 000 messages par heure, au mieux. Annoncez la durée plutôt que de la découvrir.
• Utilisez des médias hébergés chez Meta pour les envois rapides : Meta recommande d'envoyer un identifiant de média plutôt qu'une URL hébergée chez vous pour tirer parti d'un débit élevé (Meta, Throughput). Avec Genuka WA, assetId fait exactement cela.
• Ne réessayez pas à intervalle fixe. Une boucle « trois essais, une seconde d'écart » renvoie la même rafale au même moment et reprend un 130429.

Quels codes sont liés ?

• 131056 : trop de messages vers le même destinataire en peu de temps.
• 131048 : envois restreints après des blocages ou signalements, un problème de qualité et non de vitesse.
• 4 et 80007 : les deux autres limites de la même famille, qui comptent les appels à l'API de l'application et du compte WhatsApp Business, et non les messages envoyés.

FAQ

Mon numéro peut-il passer à 1 000 messages par seconde ?

Oui, automatiquement et sans frais, si trois conditions sont réunies : limite d'envoi illimitée, au moins 100 000 destinataires uniques contactés hors fenêtre de service sur 24 heures glissantes, et une note de qualité au moins moyenne. Pendant la bascule, jusqu'à une minute, le numéro répond 131057 (Meta, Throughput). Un numéro en coexistence reste à 20 messages/s.

Un message refusé en 130429 est-il facturé par Meta ?

Non. Meta ne facture un template que lorsqu'il est livré (Meta, Pricing), et un message refusé en 130429 n'est jamais parti. Côté Genuka WA, un envoi refusé ne consomme pas non plus le quota de votre abonnement : seuls les messages acceptés par Meta sont décomptés.

Pourquoi Genuka WA répond-il 400 et pas 429 ?

Parce que tous les refus de Meta sur un envoi reviennent en 400, sauf les problèmes de jeton, de permission ou d'enregistrement du numéro, en 409. La décision de réessayer se lit dans meta.retryable et meta.errorClass, conçus pour cela.

Le 130429 peut-il venir de l'API Genuka WA elle-même ?

Non. 130429 est un code de Meta, que Genuka WA relaie tel quel dans meta.code : il concerne toujours le débit du numéro émetteur chez Meta, pas votre clé API.

Sources

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