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/cepis.hpp | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'include/cepis/cepis.hpp') diff --git a/include/cepis/cepis.hpp b/include/cepis/cepis.hpp index 4ac3f1f..1861d88 100644 --- a/include/cepis/cepis.hpp +++ b/include/cepis/cepis.hpp @@ -28,8 +28,10 @@ /// ```cpp /// try { /// const cepis::Address a = cepis::lookup(cep_from_form); -/// } catch (const cepis::CepNotFound&) { -/// // the CEP does not exist: ask the user for another +/// } catch (const cepis::CepNotFound& error) { +/// // the CEP does not exist: ask the user for another. `error.faixa()` +/// // often names the municipality it would have belonged to — context for +/// // the message, never an address. /// } catch (const cepis::Error&) { /// // network, server, rate limit: retry later /// } -- cgit v1.3