Débit et limites de taux de l'API Cloud WhatsApp expliqués

Quels codes d'erreur apparaissent quand j'atteins une limite ?

Associez le code à la limite, puis choisissez la réponse.

Les codes 131048 et 131049 concernent la qualité et l'engagement plutôt que la vitesse : réessayer plus vite n'aidera pas. Voir le dépannage des codes d'erreur de l'API WhatsApp.

Sur l'API OmniChannels.ai, un rejet en amont arrive sous forme de HTTP 502 avec le code d'erreur et le texte de Meta dans message, et notre propre limitation de débit renvoie 429 avec un en-tête Retry-After. Voir erreurs et limites pour le tableau complet et les limites par défaut.

Comment mettre en file d'attente et réessayer ?

Placez une file d'attente entre votre application et l'API, limitez le débit sous votre plafond et ne réessayez que ce qui peut réussir plus tard.

1. Mettez chaque envoi en file d'attente. Votre application écrit les messages dans une file qu'un pool de workers vide. Ne parcourez jamais une liste de clients dans un seul gestionnaire de requête.
2. Limitez le débit avec un token bucket réglé sous votre débit, en laissant de la marge pour les réponses et le reste du trafic qui partage le même plafond.
3. Enregistrez d'abord chaque tentative. Écrivez une ligne par message, identifiée par votre propre ID d'opération, conservez l'ID de message renvoyé et ignorez tout ce qui a déjà été accepté.
4. Réessayez les échecs transitoires. Les limitations et les erreurs serveur temporaires sont relancées ; les erreurs de validation (400), d'authentification et de modèle ne le sont pas.
5. Appliquez un backoff avec jitter. Attendez plus longtemps après chaque tentative, ajoutez de l'aléatoire pour que les workers ne relancent pas tous en même temps, et plafonnez le délai comme le nombre de tentatives.
6. Respectez Retry-After lorsque la réponse l'inclut.
7. Vérifiez avant de renvoyer après un délai dépassé. Une réponse perdue ne signifie pas un message perdu ; consultez d'abord les événements de statut.

const RETRYABLE = new Set([429, 500, 502, 503, 504]);

async function sendWithBackoff(send, { maxAttempts = 5, baseMs = 500, capMs = 30000 } = {}) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await send();
    if (res.ok) return res;
    if (!RETRYABLE.has(res.status) || attempt === maxAttempts) throw new Error(`failed: ${res.status}`);
    const wait = Math.random() * Math.min(capMs, baseMs * 2 ** (attempt - 1)); // full jitter
    await new Promise((r) => setTimeout(r, wait));
  }
}

La page de Meta sur le débit ne donne aucune règle de backoff pour l'erreur 130429 : il s'agit d'une pratique d'ingénierie courante. Pour un 502 qui porte un code de limitation de Meta, considérez-le comme réessayable ; pour tout autre code en amont, lisez d'abord le message. Notre page erreurs et limites contient le tableau complet des reprises et la protection contre les doublons.

Comment planifier un envoi massif ?

Calculez la durée, les limites et la charge des webhooks avant de commencer.

1. Comptez les destinataires uniques et comparez-les à votre limite d'envoi. Commencez par le plan de montée en charge sûr si la liste dépasse votre palier.
2. Estimez la durée. Le nombre de messages divisé par votre débit donne des secondes. À titre de calcul, 100 000 messages à 80 par seconde prennent 1 250 secondes, soit environ 21 minutes, si rien d'autre n'utilise le plafond.
3. Réservez de la capacité. Le plafond compte aussi les messages entrants : prévoyez de la marge pour les réponses des clients pendant l'envoi.
4. Dimensionnez votre serveur de webhooks. Meta indique que les serveurs de webhooks doivent absorber trois fois votre trafic de messages sortants plus le trafic entrant attendu, avec une latence médiane inférieure ou égale à 250 ms et moins de 1 % des requêtes au-delà d'1 seconde. Voir le guide des webhooks.
5. Vérifiez d'abord la santé des modèles et la qualité, et échelonnez l'envoi par lots pour pouvoir vous arrêter si les échecs ou les blocages augmentent. Voir envoi en masse sans se faire bannir.
6. Utilisez des ID de média plutôt que des liens pour envoyer des fichiers en volume, comme le conseille Meta. Voir types de médias et limites.

Sur OmniChannels.ai, les points de terminaison en masse acceptent de nombreux destinataires dans une seule requête et un champ delay permet de ralentir la livraison. Convenez à l'avance des plans de pic avec notre équipe.

Exemple concret : une vente flash à Dubaï

« Marina Gadgets » (synthétique) prévoit un modèle de vente flash pour 60 000 clients ayant donné leur consentement.

1. Leur limite d'envoi le permet : le volume n'est donc pas la contrainte, la vitesse l'est. À 80 mps, 60 000 messages demandent 750 secondes.
2. Ils envoient en six lots de 10 000 avec un limiteur de débit à 60 mps, ce qui laisse de la marge pour les réponses.
3. Un lot affiche plusieurs erreurs 131056 pour des clients qui avaient aussi reçu une mise à jour de commande dans la même minute. Ils retardent ces envois de quelques minutes.
4. Un worker relance les requêtes limitées avec un backoff à jitter, et aucun message n'est relancé une fois qu'il a un ID.
5. Le point de terminaison de webhook stocke les événements et renvoie 200, puis un worker met à jour les statuts.
6. Après chaque lot, ils vérifient les échecs et la qualité des modèles avant de continuer.

Quelles sont les erreurs courantes ?

• Confondre les limites. Le débit, la limite par paire, les limites de la Graph API et les limites d'envoi sont des problèmes différents.
• Réessayer immédiatement, ce qui maintient le numéro au plafond et prolonge le problème.
• Envoyer au plafond, si bien que les réponses et les statuts entrent en concurrence avec la campagne.
• Renvoyer après un délai dépassé sans vérifier le statut, ce qui duplique les messages.
• Interroger en boucle les points de terminaison de la Graph API et atteindre la limite horaire.
• Des serveurs de webhooks sous-dimensionnés qui prennent du retard et déclenchent des nouvelles tentatives.
• Les limites changent. Ce guide donne les valeurs de Meta à la date de rédaction.

Comment OmniChannels.ai vous aide

BroadNet est un Business Solution Provider officiel de Meta, et OmniChannels.ai envoie WhatsApp via une seule API avec des points de terminaison en masse, un champ delay pour la limitation de débit, la planification et les statuts de livraison dans un format de webhook normalisé unique. Les revendeurs disposent de webhooks et de crédits distincts par sous-compte. Planifiez vos pics avec notre équipe, et consultez la documentation de l'API WhatsApp, les erreurs et limites et la page campagnes.