Erreurs et limites
Codes HTTP
| Code | Nom | Que faire ? |
|---|---|---|
| 200 201 | Succès | — |
| 400 | Requête invalide | Corrigez les paramètres d’après le message error. Ne réessayez pas à l’identique. |
| 401 | Non authentifié | Clé absente, mal copiée ou régénérée. Vérifiez l’en-tête x-api-key. |
| 402 | Limite de forfait / abonnement | Voir les codes ci-dessous. Changez de forfait ou attendez le mois suivant. |
| 403 | Action impossible | Numéro non connecté, accès révoqué. Lisez le message. |
| 404 | Introuvable | deviceId, contact ou webhook inexistant (ou appartenant à un autre compte). |
| 429 | Trop de requêtes | Ralentissez ; réessayez après le délai indiqué par l’en-tête RateLimit-Reset / Retry-After. |
| 500 | Erreur serveur / WhatsApp | Réessayez plus tard avec un délai croissant. |
| 501 | Non disponible | Point d’accès réservé pour une version future (listes d’audience, campagnes). |
| 502 | Refus de WhatsApp | Le destinataire n’a pas WhatsApp ou a bloqué votre numéro. Ne réessayez pas en boucle. |
Codes d’erreur métier
Certaines erreurs 402 contiennent un champ code à tester dans votre code :
| Code | Signification |
|---|---|
PLAN_LIMIT | Limite du forfait atteinte. Le champ feature précise laquelle (crm, workflows…). |
API_ACCOUNT_SUSPENDED | Abonnement expiré ou suspendu : l’accès API est bloqué. |
ACCOUNT_SUSPENDED (dans error) | Même cause, renvoyé par certaines opérations d’envoi. |
{
"error": "Limite de 2000 contacts atteinte pour votre forfait.",
"code": "PLAN_LIMIT",
"feature": "crm"
}Limites de débit
| Périmètre | Limite |
|---|---|
Envoi de messages (/whatsapp/messages/send, /whatsapp/send) | 200 requêtes / minute |
Webhooks entrants (/webhook/…) | 120 requêtes / minute |
| Toutes les autres routes de l’API | 1 000 requêtes / 15 minutes |
Les limites sont comptées par adresse IP. Chaque réponse contient l’en-tête standard RateLimit (requêtes restantes et délai de réinitialisation).
200 messages par minute est un plafond de sécurité de l’API, pas un rythme recommandé. WhatsApp peut bloquer un numéro qui envoie trop vite à des personnes qui ne l’attendent pas. Pour des messages transactionnels (confirmation, rappel), aucun souci. Pour du marketing, espacez fortement vos envois ou utilisez les campagnes.
Quotas du forfait
Les messages envoyés par l’API comptent dans le quota mensuel de messages ; les contacts créés comptent dans la limite de contacts. Suivez votre consommation dans le tableau de bord. Vous êtes prévenu par e-mail et WhatsApp à 80 % et 100 %.
Relancer intelligemment
async function sendWithRetry(body, tries = 4) {
for (let i = 0; i < tries; i++) {
const res = await fetch('https://api.whatixo.com/api/whatsapp/messages/send', {
method: 'POST',
headers: { 'x-api-key': process.env.WHATIXO_API_KEY, 'Content-Type': 'application/json' },
body: JSON.stringify(body),
});
if (res.ok) return res.json();
// Ne pas relancer les erreurs « définitives »
if ([400, 401, 402, 403, 404, 502].includes(res.status)) throw new Error((await res.json()).error);
await new Promise((r) => setTimeout(r, 2 ** i * 2000)); // 2 s, 4 s, 8 s, 16 s
}
throw new Error('Échec après plusieurs tentatives');
}