Erreurs

Mailbeam utilise les codes de statut HTTP standards. Toute réponse d'erreur porte un champ error lisible par la machine et un message lisible par un humain.

Structure d'une réponse d'erreur

{
  "error": "invalid_email_format",
  "message": "The email address is not RFC 5322 compliant.",
  "request_id": "req_01hx9abc123"
}

Testez toujours le champ error dans votre code : message peut changer, error est stable.

Codes de statut HTTP

Codes d'erreur

Erreurs d'authentification

Erreurs de validation

Erreurs de limite de débit

Erreurs serveur

Traiter les erreurs dans le code

try {
  const result = await verifyEmail(email);
  if (!result.valid) {
    // L'adresse est invalide, mais la requête a réussi — ce n'est PAS une erreur
    handleInvalidEmail(result.reason);
  }
} catch (err) {
  switch (err.code) {
    case "rate_limit_exceeded":
      await sleep(err.retryAfter * 1000);
      // réessai
      break;
    case "quota_exceeded":
      // Prévenir l'exploitation, basculer sur un repli, ou laisser passer l'inscription
      notifyOpsTeam();
      break;
    case "invalid_api_key":
    case "revoked_api_key":
      // Alerte — problème de configuration
      alertPagerDuty("Clé d'API Mailbeam invalide");
      break;
    default:
      // Journaliser et continuer — ne bloquez pas vos utilisateurs sur une erreur inattendue
      logger.error("Erreur Mailbeam", { code: err.code, requestId: err.requestId });
  }
}

Le champ reason

Quand valid vaut false, le champ reason porte une chaîne lisible par la machine qui explique pourquoi :

status face à valid

valid est un booléen, et deux états ne peuvent pas distinguer « cette boîte n'existe pas » de « nous n'avons pas pu savoir ». Servez-vous de status quand cette différence compte :

Bloquer une inscription sur undeliverable est sans danger. Bloquer sur unknown bloque de vrais utilisateurs — servez-vous du score à la place.

Ne bloquez jamais un utilisateur sur le seul catch_all_unverifiable. Servez-vous du champ score pour prendre une décision nuancée.