Errores

Mailbeam usa códigos de estado HTTP estándar. Todas las respuestas de error incluyen un campo error legible por máquina y un message legible por personas.

Estructura de una respuesta de error

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

En tu código comprueba siempre el campo error: message puede cambiar, error es estable.

Códigos de estado HTTP

Códigos de error

Errores de autenticación

Errores de validación

Errores de límite de tasa

Errores de servidor

Gestionar los errores en tu código

try {
  const result = await verifyEmail(email);
  if (!result.valid) {
    // El email es inválido pero la petición ha ido bien: esto NO es un error
    handleInvalidEmail(result.reason);
  }
} catch (err) {
  switch (err.code) {
    case "rate_limit_exceeded":
      await sleep(err.retryAfter * 1000);
      // reintenta
      break;
    case "quota_exceeded":
      // Avisa a operaciones, usa un plan B o deja pasar el registro
      notifyOpsTeam();
      break;
    case "invalid_api_key":
    case "revoked_api_key":
      // Alerta: es un problema de configuración
      alertPagerDuty("clave de API de Mailbeam no válida");
      break;
    default:
      // Registra y continúa: no bloquees usuarios por errores inesperados
      logger.error("Error de Mailbeam", { code: err.code, requestId: err.requestId });
  }
}

El campo reason

Cuando valid es false, el campo reason contiene una cadena legible por máquina que explica por qué:

status frente a valid

valid es un booleano, y con dos estados no se puede distinguir «este buzón no existe» de «no hemos podido averiguarlo». Usa status cuando esa diferencia importe:

Bloquear registros por undeliverable es seguro. Bloquear por unknown bloquea usuarios reales: usa el score en su lugar.

No bloquees nunca a un usuario solo por catch_all_unverifiable. Usa el campo score para tomar decisiones con matices.