1 files changed, 20 insertions, 1 deletions
diff --git a/src/client.lisp b/src/client.lisp
index 2965c86..9dd5338 100644
--- a/src/client.lisp
+++ b/src/client.lisp
@@ -1,6 +1,6 @@
 (in-package #:cepis)
 
-(defparameter +version+ "0.1.0"
+(defparameter +version+ "0.2.0"
   "Version of this library, as it appears in the default User-Agent.")
 
 (defparameter +default-url+ "https://cep.is"
@@ -306,6 +306,19 @@ between you and the API is answering instead of it: ~s"
             fallback))
     (error () fallback)))
 
+(defun error-faixa (body)
+  "The \"faixa\" block of an error body as a `faixa', or NIL when there is none.
+
+Every failure to read it is NIL: a body that is not JSON, a `faixa' that is not
+an object, an API too old to send the field. A not-found is a definitive answer
+about the request, and a field that only says which municipality the CEP would
+have belonged to must never be able to turn it into an `invalid-response'."
+  (handler-case
+      (let ((data (com.inuoe.jzon:parse (body-text body))))
+        (when (hash-table-p data)
+          (faixa-from-json (gethash "faixa" data))))
+    (error () nil)))
+
 (defun lookup (cep &key (client *client*))
   "Look up a single CEP and return an `address'.
 
@@ -315,6 +328,11 @@ A 400 from the API is surfaced as `invalid-cep' carrying the API's own
 message: the format already passed local validation, so the server knows
 something this client does not.
 
+A `cep-not-found' may carry a `faixa' in `cep-not-found-faixa': the
+municipality that owns the band the CEP falls in, when the API knows one. It is
+context for the error and nothing more — the answer is still a 404, and the
+band is sparse, so it says which city to ask about, never which CEPs are valid.
+
 Signals `invalid-cep' when the CEP is not 8 digits, without making a request;
 `cep-not-found' when it is well-formed but not in the database; `rate-limited'
 on 429 and `server-error' on 5xx after every attempt; `network-error' when the
@@ -325,6 +343,7 @@ request never completed; `invalid-response' when the body cannot be read."
       (case status
         (404 (error 'cep-not-found
                     :name number
+                    :faixa (error-faixa body)
                     :message (format nil "CEP ~a does not exist in the DNE database"
                                      number)))
         (400 (error 'invalid-cep