4 files changed, 34 insertions, 0 deletions
diff --git a/firefly_cli/errors.py b/firefly_cli/errors.py
new file mode 100644
index 0000000..0c0ec56
--- /dev/null
+++ b/firefly_cli/errors.py
@@ -0,0 +1,18 @@
+# Copyright (C) 2026 Danilo M. <danix@danix.xyz>  GPL-2.0-only
+
+class FireflyError(Exception):
+    """Base for all firefly-cli errors."""
+
+class ConfigError(FireflyError):
+    """Missing or invalid configuration."""
+
+class ResolutionError(FireflyError):
+    """A name could not be resolved to a single id."""
+
+class ApiError(FireflyError):
+    """Firefly returned a non-2xx response."""
+    def __init__(self, status, body):
+        self.status = status
+        self.body = body
+        msg = body.get("message") if isinstance(body, dict) else body
+        super().__init__(f"API error {status}: {msg}")
diff --git a/tests/__init__.py b/tests/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/tests/__init__.py
diff --git a/tests/unit/__init__.py b/tests/unit/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/tests/unit/__init__.py
diff --git a/tests/unit/test_errors.py b/tests/unit/test_errors.py
new file mode 100644
index 0000000..63731c5
--- /dev/null
+++ b/tests/unit/test_errors.py
@@ -0,0 +1,16 @@
+import unittest
+from firefly_cli.errors import FireflyError, ConfigError, ApiError, ResolutionError
+
+class TestErrors(unittest.TestCase):
+    def test_subclassing(self):
+        for cls in (ConfigError, ApiError, ResolutionError):
+            self.assertTrue(issubclass(cls, FireflyError))
+
+    def test_api_error_carries_status_and_body(self):
+        e = ApiError(422, {"message": "bad"})
+        self.assertEqual(e.status, 422)
+        self.assertEqual(e.body, {"message": "bad"})
+        self.assertIn("422", str(e))
+
+if __name__ == "__main__":
+    unittest.main()