· 6 min · TextMeFlow Team

Erreurs de l'API WhatsApp : 401, 400, 409, 413 et 429 expliquées

La plupart des intégrations sont construites et testées sur le cas idéal : numéro valide, appareil connecté, petit message texte. La première fois que quelque chose tourne mal en production, la réponse d'erreur est le seul indice dont vous disposez. Voici un guide de terrain sur les erreurs que renvoie réellement POST /v1/messages, ce qui déclenche chacune d'elles et ce que votre code doit en faire.

401 — clé API invalide ou absente

La cause la plus fréquente n'est pas une mauvaise clé, mais une clé expirée ou révoquée — par exemple après une rotation des clés dans le tableau de bord, en oubliant de mettre à jour une intégration déjà déployée. Une erreur 401 ne doit jamais être retentée automatiquement : réessayer avec la même clé invalide ne fait que gaspiller des requêtes. Journalisez-la bruyamment et alertez un humain, car cela signifie généralement que tous les envois échouent, pas un seul.

400 invalid_recipient — numéro de téléphone mal formaté

C'est de loin le motif de rejet le plus courant sur les nouveaux comptes. L'API attend le format E.164 (+ suivi de l'indicatif du pays et du numéro, sans espaces, sans zéro initial après l'indicatif). Un numéro collé depuis un tableur ou un champ de formulaire conserve souvent sa mise en forme locale, comme 06 12 34 56 78 au lieu de +33612345678, et l'API le rejette avant même qu'il n'atteigne WhatsApp. Si vous en voyez beaucoup, validez et normalisez les numéros avant qu'ils n'arrivent à l'API — la regex et les étapes de normalisation figurent dans le guide complet sur la validation des numéros de téléphone.

409 — session non connectée

Cela signifie que l'appareil WhatsApp lié à votre compte n'est pas actif pour le moment : il a été déconnecté depuis le téléphone, a perdu sa connexion ou n'a jamais été associé. Aucune nouvelle tentative n'y changera rien — la solution consiste à scanner de nouveau le code QR depuis le tableau de bord. Si vous effectuez des envois sans surveillance (une tâche de rappel nocturne, par exemple), écoutez l'événement webhook session.disconnected pour être averti d'une association rompue avant que votre prochain lot n'échoue complètement, plutôt que de le découvrir à travers une pile d'erreurs 409. Le cycle de vie complet de l'association — ce qui provoque une déconnexion et comment fonctionne la nouvelle association — est décrit dans comment fonctionne l'association WhatsApp sur TextMeFlow.

413 / 415 — média trop volumineux ou type non pris en charge

TextMeFlow accepte des médias jusqu'à 100 Mo par fichier. Une erreur 413 signifie que le fichier dépasse cette limite ; une erreur 415 signifie que le type de fichier ou le type MIME n'est pas pris en charge par WhatsApp pour ce type de message (un .docx envoyé comme message « image », par exemple). Compressez ou convertissez avant l'envoi plutôt que de réessayer — le fichier ne va pas rétrécir tout seul. Les détails sur les types pris en charge et sur le endpoint média se trouvent dans la documentation média.

429 — deux significations différentes

Une erreur 429 ne correspond pas toujours au même problème. TextMeFlow la renvoie pour deux raisons distinctes, que l'on distingue grâce au champ reason ou error du corps de la réponse :

  • burst_exceeded / hourly_exceeded — vous avez atteint la limite de débit par numéro (1 message/seconde, 60/minute, 1 000/heure) qui évite que votre numéro ressemble à une source de spam. C'est temporaire : patientez et réessayez. Le guide des limites de débit donne tous les chiffres, et gérer les limites de débit et le statut des messages propose du code de nouvelle tentative fonctionnel pour Node et Python.
  • quota_exceeded — vous avez épuisé le quota mensuel de messages de votre plan (le plan Free offre 50 messages/mois, les plans payants démarrent à 5 €/mois). Celle-ci ne se résout pas d'elle-même ; réessayer ne sert à rien tant que vous ne passez pas à un plan supérieur ou que la période de facturation ne se renouvelle pas.

Traiter les deux comme « il suffit de réessayer » est un bug courant — la seconde réessaiera indéfiniment sans jamais aboutir.

Le destinataire s'est désinscrit (STOP)

Si un destinataire a déjà répondu STOP (ou l'équivalent dans la langue utilisée par votre flux), le pipeline anti-spam de TextMeFlow bloque tout envoi ultérieur vers ce numéro, quelle que soit la demande de votre intégration. Ce n'est pas un bug à contourner : c'est une gestion de désinscription obligatoire, et renvoyer des messages à un numéro désinscrit est aussi exactement ainsi que des numéros se font signaler et bannir par WhatsApp lui-même. Le pipeline anti-spam complet (limites de débit, score de risque, gestion du STOP, heures calmes) est décrit dans la documentation anti-spam.

Une gestion des erreurs qui n'aggrave pas la situation

Un petit modèle mental pour la logique de nouvelle tentative :

  • Ne jamais réessayer : 401 (authentification), 400 (validation — la requête elle-même est incorrecte), 415 (type non pris en charge), quota_exceeded.
  • Réessayer avec un délai croissant : 429 avec burst_exceeded ou hourly_exceeded, et erreurs serveur 5xx.
  • Corriger la cause, ne pas réessayer : erreurs de session 409 (nouvelle association), 413 (réduire le fichier).

Journaliser le corps brut de l'erreur — et pas seulement le code de statut — accélère nettement le diagnostic, car les réponses d'erreur de TextMeFlow contiennent un motif lisible par machine en plus du statut HTTP.

Envie de voir ces réponses sur un vrai compte plutôt que d'en lire la description ? Commencez gratuitement et envoyez votre premier message en quelques minutes — le plan gratuit inclut 50 messages, de quoi tester chacun des cas d'erreur ci-dessus.

Envie d'envoyer des messages WhatsApp via API ?

Gratuit pour toujours jusqu'à 50 messages/mois. Scannez un QR et envoyez votre premier message en 5 minutes.

Gratuit pour toujours