Référence
Erreurs & limites
Codes HTTP, champs d'erreur JSON et limites métier de l'API publique v1.
Format d'erreur
Les réponses d'erreur incluent généralement statusCode, error (code machine) et message (lisible).
{
"statusCode": 403,
"error": "insufficient_scope",
"message": "Scopes requis : messages:send"
}Codes HTTP
| HTTP | Code | Signification | Action |
|---|---|---|---|
| 401 | unauthorized | Clé API absente, invalide, expirée ou révoquée. | Vérifiez l’en-tête X-API-Key. Recréez une clé si nécessaire. |
| 403 | plan_required | Compte sans accès API (plan Gratuit sans add-on). | Activez l’add-on Accès API ou passez au plan Starter. |
| 403 | insufficient_scope | La clé n’a pas le scope requis pour cet endpoint. | Créez une clé avec les scopes adéquats (ex. messages:send). |
| 429 | rate_limit_exceeded | Trop de requêtes HTTP sur la fenêtre d’une minute. | Attendez ou étalez les appels. Limite selon plan (voir Authentification). |
| 429 | too_many_auth_failures | Trop de tentatives d’authentification échouées depuis votre IP (20 en 5 min). | Attendez quelques minutes, corrigez la clé avant de réessayer. |
Limites métier
- Quota messagesLes envois API consomment le même token bucket que le dashboard (campagnes incluses).
- OTP5 envois / heure / numéro · 100 envois / heure / compte.
- Envoi en lot (bulk)Cap destinataires par appel selon plan · 1 requête bulk / minute / clé.
- Idempotency-KeyEn-tête optionnel sur POST send / send-media — même clé + même corps = réponse mise en cache 24 h.
- Clés testPréfixe rfl_test_ — dry-run si API_TEST_KEYS_DRY_RUN=true (aucun WhatsApp réel).
Limites HTTP par plan : Authentification.