1 files changed, 30 insertions, 0 deletions
diff --git a/include/cepis/errors.hpp b/include/cepis/errors.hpp
index 0420ecd..fa928f0 100644
--- a/include/cepis/errors.hpp
+++ b/include/cepis/errors.hpp
@@ -4,6 +4,9 @@
 #include <optional>
 #include <stdexcept>
 #include <string>
+#include <utility>
+
+#include "cepis/models.hpp"
 
 namespace cepis {
 
@@ -38,9 +41,36 @@ class InvalidCep : public Error {
 };
 
 /// The CEP is well-formed but does not exist in the DNE database.
+///
+/// The API often says **where it would have been** — see `faixa()`. That is
+/// still a not-found: the extra context does not make the CEP deliverable, and
+/// this remains the exception thrown for it.
 class CepNotFound : public Error {
  public:
   using Error::Error;
+
+  CepNotFound(const std::string& message, std::optional<Faixa> faixa)
+      : Error(message), faixa_(std::move(faixa)) {}
+
+  /// The municipality the CEP would have belonged to, when the API names one.
+  ///
+  /// `std::nullopt` when the CEP falls in a band no municipality owns — the
+  /// API **omits** the block there, it never sends null — and also whenever
+  /// the block cannot be read. Read `Faixa` before showing any of it: the
+  /// range it describes is sparse, and the CEP does not exist either way.
+  ///
+  /// ```cpp
+  /// } catch (const cepis::CepNotFound& error) {
+  ///   if (error.faixa()) {
+  ///     std::cerr << "not found; did you mean somewhere in "
+  ///               << error.faixa()->localidade << '/' << error.faixa()->uf << "?\n";
+  ///   }
+  /// }
+  /// ```
+  [[nodiscard]] const std::optional<Faixa>& faixa() const noexcept { return faixa_; }
+
+ private:
+  std::optional<Faixa> faixa_;
 };
 
 /// The request never completed: DNS, refused connection, timeout, TLS.