Add GMTParameterError and deprecate GMTInvalidInput

Author: Chuan1937

doc/api/index.rst

@@ -294,6 +294,7 @@ All custom exceptions are derived from :class:`pygmt.exceptions.GMTError`.
 
     exceptions.GMTError
     exceptions.GMTInvalidInput
+    exceptions.GMTParameterError
     exceptions.GMTVersionError
     exceptions.GMTOSError
     exceptions.GMTCLibError

pygmt/exceptions.py

@@ -41,7 +41,55 @@ class GMTCLibNoSessionError(GMTCLibError):
 class GMTInvalidInput(GMTError):  # noqa: N818
     """
     Raised when the input of a function/method is invalid.
+
+    .. deprecated:: 0.13.0
+        Use :class:`GMTParameterError` instead.
+    """
+
+
+class GMTParameterError(GMTError):  # noqa: N818
     """
+    Raised when parameters are missing or invalid.
+
+    Parameters
+    ----------
+    required
+        Names of required parameters.
+    require_any
+        Names of parameters where at least one must be specified.
+    exclusive
+        Names of mutually exclusive parameters.
+    reason
+        Detailed reason why the parameters are invalid.
+    """
+
+    def __init__(
+        self,
+        *,
+        required: set[str] | None = None,
+        require_any: set[str] | None = None,
+        exclusive: set[str] | None = None,
+        reason: str | None = None,
+    ):
+        msg = []
+        if required:
+            msg.append(
+                "Required parameter(s) are missing: "
+                f"{', '.join(repr(par) for par in required)}."
+            )
+        if require_any:
+            msg.append(
+                "At least one of the following parameters must be specified: "
+                f"{', '.join(repr(par) for par in require_any)}."
+            )
+        if exclusive:
+            msg.append(
+                "Mutually exclusive parameter(s) are specified: "
+                f"{', '.join(repr(par) for par in exclusive)}."
+            )
+        if reason:
+            msg.append(reason)
+        super().__init__(" ".join(msg))
 
 
 class GMTVersionError(GMTError):