From b402de683eecef4c890081dd72edbcaf57f375e0 Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:32:01 -0300 Subject: Expose the band of a CEP that does not exist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A CEP that fails a lookup is rarely a random number: it is someone who knows the city and guessed the digits, most often the -000 that 957 municipalities never received. The API now answers that 404 with an optional faixa naming the municipality those numbers belong to, so the caller can say "not found, but you seem to be looking at Areal/RJ" instead of just "not found". It stays an error. Faixa hangs off CEPNotFound and nothing about it promotes a nonexistent CEP into an address. Its cep_ini/cep_fim are the smallest and largest CEP that really exist there, not the published bounds — the DNE's own start for Areal is the CEP that just failed — and the band is sparse, which is what ceps is for; both facts are spelled out in the docs so nobody iterates the pair. Parsing is deliberately toothless: a missing, empty or malformed faixa, or a 404 body that is not JSON at all, all yield nil. Losing the consolation prize must never replace a clean not-found with a parse failure. --- lib/cepis.rb | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'lib/cepis.rb') diff --git a/lib/cepis.rb b/lib/cepis.rb index 7b2cc5a..39cd831 100644 --- a/lib/cepis.rb +++ b/lib/cepis.rb @@ -27,8 +27,11 @@ require_relative "cepis/client" # # begin # address = Cepis.lookup(cep_from_form) -# rescue Cepis::CEPNotFound -# # the CEP does not exist: ask the user for another +# rescue Cepis::CEPNotFound => e +# # the CEP does not exist: ask the user for another. e.faixa, when the +# # API sends it, names the municipality whose numbers surround the one +# # that failed — context for the error, never an address. +# puts "did you mean somewhere in #{e.faixa.localidade}?" if e.faixa # rescue Cepis::Error # # network, server, rate limit: retry later # end -- cgit v1.3