Expose the band of a CEP that does not existHEADv0.2.0main

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.

1 files changed, 5 insertions, 2 deletions

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