Codes d'erreur

Toutes les erreurs renvoyées par l'API, ce qu'elles signifient et comment y réagir.

Toute erreur suit la même forme :

json

{
  "success": false,
  "error": {
    "code": "quota_exceeded",
    "message": "Quota mensuel atteint (100/100)."
  }
}

error.code est stable dans le temps : c'est lui qu'il faut tester dans votre code. error.message est destiné aux humains et peut être reformulé.

Authentification et accès

HTTP	Code	Signification et correction
401	`missing_api_key`	Aucune clé fournie. Ajoutez l'en-tête `X-API-Key`.
401	`invalid_api_key`	Clé inconnue ou révoquée. Vérifiez qu'elle est active dans Clés API.
403	`account_inactive`	Compte suspendu ou supprimé. Contactez le support.
403	`ip_not_allowed`	L'adresse IP appelante n'est pas dans la liste blanche de cette clé. Ajoutez-la dans IP autorisées — l'IP réellement vue par le service est indiquée dans le message d'erreur.
403	`feature_not_available`	Fonctionnalité absente de votre forfait (templates, pièces jointes). Voir Quotas et limites.

Requête

HTTP	Code	Signification et correction
405	`method_not_allowed`	Utilisez `POST` (ou `GET`).
400	`invalid_json`	`Content-Type: application/json` annoncé, mais corps illisible. Vérifiez les virgules et les guillemets.
422	`invalid_request`	Le message n'est pas valide. Le détail est dans `message` : paramètre requis manquant, adresse mal formée, trop de destinataires, format inconnu, variable de template non fournie, pièce jointe refusée ou trop volumineuse.
404	`template_not_found`	Aucun template ne porte cet identifiant sur votre compte. Vérifiez le slug dans Templates.

Quotas et débit

HTTP	Code	Signification et correction
429	`quota_exceeded`	Quota mensuel atteint. La réponse contient `quota.used` et `quota.quota`. Le compteur repart au 1^er du mois (UTC), ou changez de forfait.
429	`rate_limited`	Limite de débit atteinte sur une fenêtre (minute, heure, jour ou mois). La réponse contient `retry_after`, en secondes : attendez ce délai avant de réessayer.

json · HTTP 429

{
  "success": false,
  "error": { "code": "rate_limited", "message": "Limite de débit dépassée (fenêtre : minute)." },
  "retry_after": 27
}

Service et envoi

HTTP	Code	Signification et correction
502	`smtp_error`	Le serveur SMTP a refusé le message. Le message d'erreur reprend sa réponse brute (authentification, expéditeur rejeté, destinataire inconnu…). Voir Ajouter un compte SMTP.
500	`no_smtp_account`	La clé API n'a plus de compte SMTP rattaché (compte supprimé). Créez une nouvelle clé.
500	`smtp_config_error`	Les identifiants SMTP stockés sont illisibles. Ré-enregistrez le compte SMTP.
500	`internal_error`	Erreur interne pendant le contrôle de quota. Réessayez ; si cela persiste, contactez le support.
503	`db_unavailable`	Base de données indisponible. Réessayez dans quelques instants.
503	`migrations_pending`	Maintenance en cours (mise à jour du schéma). Réessayez dans quelques instants.

Stratégie de réessai recommandée

Situation	Que faire
4xx de validation (`invalid_request`, `invalid_json`…)	Ne pas réessayer : la requête est fautive, corrigez l'appel.
401 / 403	Ne pas réessayer : problème de clé, d'IP ou de forfait.
429 `rate_limited`	Attendre `retry_after` secondes, puis réessayer.
429 `quota_exceeded`	Ne pas boucler : mettre en file d'attente et alerter.
502 / 503	Réessayer avec un délai croissant (1 s, 5 s, 30 s), 3 fois maximum.

Attention

Un 502 signifie que l'envoi a été tenté et a échoué : le quota a été décompté. Réessayer consomme donc un nouvel emplacement de quota. Limitez le nombre de tentatives et journalisez l'échec.