From 2fb251996798798af38903fe535b8d147084a50a Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:33:51 -0300 Subject: Expose the municipality behind a not-found CEP MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A CEP that fails a lookup is rarely random: it is usually someone who knows the city and guessed the number, and the classic guess is the -000 that 957 municipalities never received. The API now names, on the 404 itself, the municipality that CEP would have belonged to, so a caller can say "not found — did you mean somewhere in Areal/RJ?" instead of just "not found". CepNotFound carries it as an optional Faixa. It stays an error: the block is context, not an address, and the range it describes is sparse, which is why it reports a count alongside the first and last CEP that actually exist there rather than the bounds the Correios publish. Parsing it is best-effort on purpose — a missing, empty or malformed block leaves the optional empty, since a 404 is already the answer and reading the hint attached to it must never cost the diagnosis. --- include/cepis/client.hpp | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'include/cepis/client.hpp') diff --git a/include/cepis/client.hpp b/include/cepis/client.hpp index 205ba85..3a0d863 100644 --- a/include/cepis/client.hpp +++ b/include/cepis/client.hpp @@ -15,7 +15,7 @@ namespace cepis { /// The library version, as it appears in the default `User-Agent`. -inline constexpr std::string_view kVersion = "0.1.0"; +inline constexpr std::string_view kVersion = "0.2.0"; /// Where the public API lives. inline constexpr std::string_view kDefaultBaseUrl = "https://cep.is"; @@ -33,7 +33,7 @@ inline constexpr std::size_t kMaxBatch = 500; /// trip for the server to say so wastes both sides' time. std::string normalize_cep(std::string_view value); -/// The default `User-Agent`, e.g. `cepis-cpp/0.1.0 (+https://cep.is)`. +/// The default `User-Agent`, e.g. `cepis-cpp/0.2.0 (+https://cep.is)`. std::string default_user_agent(); /// How a `Client` behaves. Every field has a working default; in practice only @@ -108,6 +108,9 @@ class Client { /// 5xx after every attempt; `NetworkError` when the request never /// completed; `InvalidResponse` when a success status carries a body that /// is not a JSON object. + /// + /// A `CepNotFound` often carries `faixa()`, the municipality the CEP would + /// have belonged to. It is context for the error, not an address. [[nodiscard]] Address lookup(std::string_view cep) const; /// Looks up many CEPs in one batch. -- cgit v1.3