Carry the municipality of a CEP that does not existHEADv0.2.0main

A CEP that fails is rarely random: it is someone who knows the city and
guessed the number, most often the -000 that 957 municipalities never
received. The API now answers that 404 with the municipality owning the
band the CEP falls in, and without it every caller can say no more than
"does not exist" to a person who is one digit away from the right CEP.

It lands on the condition rather than in a return value because it is
context for the failure and nothing else: the answer is still a 404, and
a faixa must never read as an address that resolved. Parsing it is
deliberately defensive for the same reason — a missing, malformed or
empty block yields NIL, so a field that only adds context cannot turn a
clean not-found into a parse failure, and an older API stays supported.

The ends of the band are the CEPs that actually exist, not the bounds
the Correios publish, and the band is sparse; the docstrings and the
README say so, because presenting the pair as a range of valid CEPs is
the mistake this data invites.

models is compiled before errors so the report function can name the
faixa's municipality.

1 files changed, 19 insertions, 2 deletions

diff --git a/src/errors.lisp b/src/errors.lisp
index 525ac67..ea6f83f 100644
--- a/src/errors.lisp
+++ b/src/errors.lisp
@@ -30,12 +30,29 @@ Usually signalled without a request ever being made — the client checks the
 format before going to the network."))
 
 (define-condition cep-not-found (cepis-error cell-error)
-  ()
+  ((faixa :initarg :faixa
+          :initform nil
+          :reader cep-not-found-faixa
+          :documentation
+          "The municipality owning the band this CEP falls in, or NIL."))
+  (:report (lambda (condition stream)
+             (write-string (error-message condition) stream)
+             (let ((faixa (cep-not-found-faixa condition)))
+               (when faixa
+                 (format stream " — it falls in the band of ~a/~a"
+                         (faixa-localidade faixa)
+                         (faixa-uf faixa))))))
   (:documentation
    "The CEP is well-formed but does not exist in the DNE database.
 
 Also a `cell-error', which is the closest thing the standard has to a failed
-key lookup: `cell-error-name' returns the CEP that was not found."))
+key lookup: `cell-error-name' returns the CEP that was not found.
+
+`cep-not-found-faixa' is a `faixa' naming the municipality that owns the band
+the CEP falls in, when the API knows one, and NIL otherwise — either because
+no municipality owns that band or because an older API is answering. It is
+context for the error, not an address: this is still a 404, and a caller must
+not read a municipality here as a CEP that resolved."))
 
 (define-condition network-error (cepis-error)
   ()