1 files changed, 34 insertions, 0 deletions
diff --git a/lib/cepis/CepisException.php b/lib/cepis/CepisException.php
new file mode 100644
index 0000000..efd1a86
--- /dev/null
+++ b/lib/cepis/CepisException.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cepis;
+
+/**
+ * Implemented by every exception this library throws. Catch it to handle any
+ * failure with one handler.
+ *
+ * It is an interface rather than a base class so that each concrete exception
+ * can also extend the SPL type a PHP developer would already be catching:
+ * {@see InvalidCepException} is an `\InvalidArgumentException`, so code that
+ * already validates input keeps working without knowing this library exists,
+ * and {@see CepNotFoundException} is an `\OutOfBoundsException`, because
+ * looking a CEP up is conceptually a key lookup. PHP has single inheritance;
+ * a marker interface is the only way to have both.
+ *
+ * Below this interface the split is by **the decision the caller has to
+ * make**, not by the HTTP status that caused it:
+ *
+ * - {@see InvalidCepException} and {@see CepNotFoundException} are problems
+ *   with the *request*. Retrying is pointless — the same CEP will fail again.
+ * - {@see NetworkException}, {@see ServerErrorException} and
+ *   {@see RateLimitedException} are problems with *transport*. Retrying may
+ *   help, and the client already retried on its own before throwing.
+ *
+ * That split is why `CepNotFoundException` is not "the HTTP 404 exception":
+ * `InvalidCepException` is thrown without any request being made at all, when
+ * the CEP is malformed before it ever leaves the machine.
+ */
+interface CepisException extends \Throwable
+{
+}