Erreur WhatsApp 4 : limite d'appels de l'app, solution

L'erreur WhatsApp 4 signifie que l'application qui appelle l'API de Meta a atteint sa limite d'appels. C'est une limitation temporaire : rien n'est cassé, il faut attendre et réduire le volume de requêtes. Elle vise l'application dans son ensemble, et non un numéro ou un compte WhatsApp, ce qui la distingue des erreurs 80007 et 130429.

Que signifie l'erreur 4 ?

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

« The app has reached its API call rate limit. » — Meta, codes d'erreur de la Cloud API

La solution proposée : ouvrir l'app dans le tableau de bord d'app, section Application Rate Limit, vérifier que la limite est atteinte, puis réessayer plus tard ou réduire la fréquence et le nombre de requêtes. La documentation de Graph appelle ce code « API Too Many Calls », un problème temporaire de limitation : « Wait and retry the operation, or examine your API request volume » (Meta, Graph API, gestion des erreurs). Sa page sur les limites précise que le code 4 indique que l'app dont le jeton est utilisé a atteint sa limite (Meta, Rate limits).

Quatre limites, quatre codes

Les chiffres viennent de la présentation de la plateforme (Meta, About the platform).

Quand l'erreur 4 apparaît-elle ?

• Une rafale d'appels qui ne sont pas des envois : lister les templates en boucle, relire la santé de chaque numéro à chaque affichage d'un tableau de bord, téléverser des médias à la chaîne.
• Plusieurs services sur la même app : un worker de campagne, un back-office et un script de synchronisation qui partagent le même jeton additionnent leurs appels.
• Une boucle de réessais sans délai : chaque échec relance immédiatement un appel, et la limite s'éloigne au lieu de se rapprocher.

Où la voir dans Genuka WA ?

Avec Genuka WA, l'application Meta qui appelle est celle de Genuka, Tech Provider : la limite d'application ne dépend pas que de votre volume. Genuka range le code 4 dans la classe retryable.

Ce 502 arrive sans corps JSON : notre CDN remplace la réponse par la seule ligne error code: 502 (référence API). Traitez-le comme un échec passager, sans chercher meta dedans.

Genuka limite aussi de lui-même les rafales qu'il pourrait provoquer pour vous : GET /api/v1/numbers?refresh=true refuse l'appel (400 too_many_connections) au-delà de 25 numéros, restreignez-le avec ?companyId= ; et une actualisation de templates traite les comptes WhatsApp cinq par cinq.

Comment corriger l'erreur 4 ?

Si vous appelez la Cloud API avec votre propre app, le tableau de bord d'app affiche le pourcentage d'utilisation de la limite d'application et le nombre d'utilisateurs limités (Meta, Rate limits).

const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

export async function callGenuka(path: string, body: unknown, maxAttempts = 5) {
  for (let attempt = 1; ; attempt++) {
    const response = await fetch(`https://wa.genuka.com/api/v1${path}`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });
    // Un 5xx arrive sans JSON : notre CDN le remplace par « error code: 502 ».
    const json = await response.json().catch(() => null);
    if (response.ok) return json.data;

    // Un envoi n'est relancé que sur un code de Meta (4, 80007, 130429…) : après un délai
    // dépassé, Meta a peut-être déjà accepté le message, et le renvoyer le doublerait.
    const retryable =
      path === "/messages"
        ? json?.meta?.retryable === true && json.meta.code !== undefined
        : response.status >= 500 || json?.meta?.retryable === true;
    if (!retryable || attempt >= maxAttempts) {
      throw new Error(`${response.status} ${json?.error ?? "sans corps JSON"} (Meta ${json?.meta?.code ?? "-"})`);
    }
    const base = Math.min(30_000, 1_000 * 2 ** (attempt - 1));
    await sleep(base / 2 + Math.random() * (base / 2));
  }
}

Comment éviter l'erreur 4 ?

• Préférez les webhooks au polling. Statuts de messages, revues de templates et changements de qualité arrivent d'eux-mêmes ; les redemander en boucle consomme la limite pour rien.
• Passez les envois de masse par une campagne. Genuka cadence l'envoi au débit du numéro et gère les réessais destinataire par destinataire — voir campagnes par API.
• Ne réessayez jamais à intervalle fixe. Trois essais à une seconde d'écart renvoient la même rafale au même moment.

Quels codes sont liés ?

• 80007 : la limite d'appels d'une app sur un compte WhatsApp.
• 130429 : le débit de messages par seconde d'un numéro.
• 131056 : trop de messages vers le même destinataire en peu de temps.

FAQ

L'erreur 4 vient-elle de ma clé API Genuka ?

Non. C'est un code de Meta, relayé dans meta.code. Il concerne l'application Meta qui fait l'appel, celle de Genuka, et non votre clé.

Combien de temps faut-il attendre ?

Meta ne donne pas de durée fixe pour le code 4 : les limites de Graph se calculent sur une heure glissante. Commencez par un délai croissant, d'une à trente secondes, et réduisez vos appels ; si l'erreur dure plus d'une heure, prévenez le support.

Un message refusé avec le code 4 est-il facturé ?

Il n'a pas été accepté par Meta, il n'y a donc pas de message à facturer. Côté Genuka WA, seuls les messages acceptés par Meta comptent dans le quota de votre abonnement.

Sources

• Meta — Error codes
• Meta — Graph API, Handling errors
• Meta — Graph API, Rate limits
• Meta — About the platform, rate limits