Gérer les erreurs et les retries de l'API WhatsApp Business

L'API WhatsApp Business Cloud de Meta retourne des erreurs HTTP standard complétées par un système de codes d'erreur propriétaires. Toute intégration en production doit être capable d'identifier ces erreurs, de distinguer celles qui méritent un retry de celles qui n'en valent pas la peine, et d'implémenter une stratégie de backoff pour ne pas aggraver une situation de surcharge. Ignorer cette couche de gestion d'erreurs, c'est garantir des pertes de messages silencieuses et des alertes à 3h du matin.

La structure des erreurs retournées par Meta

L'API Graph retourne les erreurs dans un objet JSON standardisé imbriqué dans une clé error :

{
  "error": {
    "message": "Invalid OAuth access token",
    "type": "OAuthException",
    "code": 190,
    "fbtrace_id": "AbCdEfGhIjK"
  }
}

Le champ fbtrace_id est important : c'est l'identifiant de trace Meta, à conserver dans vos logs pour tout échange avec le support.

Pour les messages envoyés, les erreurs de livraison arrivent via webhook (événement de type statuses avec status: "failed") et contiennent un objet errors avec un code et un title.

Cartographie des codes d'erreur courants

Code	Signification	Stratégie
100	Paramètre invalide (payload malformé)	Pas de retry — corriger le payload
130429	Rate limit atteint	Retry avec backoff exponentiel
131026	Message non délivrable (numéro invalide ou non WhatsApp)	Pas de retry — marquer le contact
131047	Fenêtre de 24h expirée	Pas de retry — envoyer un template HSM à la place
131056	Paire (numéro expéditeur, numéro destinataire) bloquée	Pas de retry — contacter le support Meta
133004	Compte suspendu	Pas de retry — action manuelle requise
190	Token d'accès invalide ou expiré	Retry après renouvellement du token
200-299	Permissions insuffisantes	Pas de retry — corriger les scopes

Cette distinction "retryable vs non-retryable" est le premier filtre à implémenter dans votre gestionnaire d'erreurs.

Concevoir une stratégie de retry robuste

Un retry naïf (réessayer immédiatement en boucle) aggrave les problèmes de rate limiting et peut conduire à une suspension temporaire du numéro. La bonne approche combine plusieurs mécanismes.

Backoff exponentiel avec jitter

Pour les erreurs 130429 (rate limit) et les erreurs réseau transitoires (timeout, 503), appliquez un backoff exponentiel : attendez 1s, puis 2s, puis 4s, puis 8s, avec un délai maximum (ex. 5 minutes). Ajoutez un jitter (variation aléatoire ±20 %) pour éviter que tous vos workers retentent exactement au même moment.

Queue de messages avec DLQ

Architecturez vos envois autour d'une queue de messages (SQS, RabbitMQ, BullMQ) plutôt que des appels API synchrones. Chaque message en file d'attente peut être réessayé N fois avant d'être envoyé dans une Dead Letter Queue (DLQ) pour analyse manuelle. Ce pattern vous donne visibilité sur les messages qui échouent de façon répétée.

Idempotence côté client

L'API WhatsApp n'expose pas de mécanisme d'idempotence natif sur l'envoi de messages. Si votre worker envoie un message et ne reçoit pas de réponse (timeout réseau), il ne sait pas si le message a bien été envoyé côté Meta. Pour éviter les doublons, associez chaque tentative d'envoi à un identifiant interne unique, et vérifiez les webhooks de livraison (message_id retourné par Meta) avant de réessayer.

Monitoring et alertes en production

Une intégration saine surveille activement les erreurs. Voici les métriques à instrumenter :

• Taux d'erreur par code : un pic de 131026 indique une dégradation de la qualité de votre base de contacts ; un pic de 130429 indique que vous approchez des limites de messagerie de votre tier.
• Taux de messages en DLQ : au-delà d'un seuil (ex. 0,5 % des messages envoyés), déclencher une alerte.
• Latence des webhooks de livraison : si les confirmations de livraison tardent, cela peut indiquer un problème côté Meta ou un problème de traitement de vos webhooks.
• Score qualité du numéro : Meta expose un score qualité (GREEN / YELLOW / RED) via l'API et les webhooks phone_number_quality_update. Un score dégradé précède souvent une limitation ou une suspension.

Pour les fondations de l'implémentation des webhooks, référez-vous au guide complet de l'API WhatsApp Business. Pour sécuriser la réception de ces webhooks, consultez Sécuriser son intégration API WhatsApp.

Gestion des limites de messagerie par tier

L'API WhatsApp segmente les numéros en tiers selon le volume de messages initiés envoyés sur 24 heures glissantes :

Tier	Limite quotidienne
1	1 000 conversations
2	10 000 conversations
3	100 000 conversations
4	Illimité

La montée de tier est automatique : Meta élève le tier d'un numéro qui atteint 80 % de sa limite deux jours de suite, à condition que le score qualité soit GREEN. Une stratégie de retry trop agressive qui génère des signalements utilisateur peut bloquer cette montée de tier ou provoquer une rétrogradation.

FAQ

Comment savoir si un message a bien été envoyé sans webhook de confirmation ?

Si vous avez envoyé un message et n'avez pas reçu de webhook sent ou delivered dans les 30 secondes, ne réessayez pas immédiatement. Attendez le délai de grâce (généralement quelques minutes), puis vérifiez dans votre DLQ. Une absence de confirmation peut être due à un délai réseau ou à un problème transitoire Meta, pas nécessairement à un échec d'envoi.

L'erreur 131047 (fenêtre 24h expirée) peut-elle être évitée ?

Oui, en anticipant l'expiration de la fenêtre de conversation. Si votre dernier échange avec un utilisateur date de plus de 20 heures, envoyez un message de type service (si la fenêtre est encore ouverte) ou basculez sur un template HSM approuvé de catégorie UTILITY ou MARKETING. L'erreur 131047 ne peut pas être retryée : la seule solution est d'envoyer un template.

Comment tester la gestion d'erreurs sans impacter la production ?

Utilisez le bac à sable Meta pour l'API WhatsApp pour simuler des envois. Pour tester spécifiquement des scénarios d'erreur (numéro invalide, rate limit), créez un environnement de staging avec un numéro de test dédié et des numéros destinataires de test fournis par Meta.

Un token expiré génère-t-il une erreur retryable ?

L'erreur 190 (token expiré) est retryable une fois le token renouvelé. Votre système doit détecter ce code spécifiquement, déclencher le renouvellement du token (via votre vault de secrets), puis rejouer les messages en attente. Ne retenez pas les messages en file pendant le renouvellement — cela peut créer un effet de "thundering herd" au redémarrage.

---

Gérer correctement les erreurs de l'API WhatsApp Business est la différence entre une intégration fragile et une plateforme de production fiable. Codes d'erreur documentés, stratégie de retry avec backoff, queue avec DLQ et monitoring actif : ces quatre éléments forment le socle d'une intégration robuste. Pour démarrer sur une infrastructure déjà éprouvée, découvrez l'API WhatsApp Business de Whakup, Meta Tech Provider certifié.