Report the municipality a missing CEP would have belonged toHEADv0.2.0main

A CEP that fails a lookup is rarely a random number: it is usually someone
who knows the city and guessed, and the classic guess is the -000 that 957
municipalities never received. The API now answers those 404s with a faixa
naming the municipality that owns the band the number fell into, which is
the difference between telling a user "invalid CEP" and "no such CEP in
Areal/RJ".

It is context for an error and never an address, so it rides on the
cepis_not_found condition instead of turning the failure into a success,
and cep_ini/cep_fim are the endpoints that exist rather than the range the
Correios publish - the interval between them is sparse, which is what ceps
counts. Parsing is deliberately unable to signal: a faixa that is null, an
array, a string or half a body leaves a clean not-found behind, because the
caller asked for the CEP, not for the decoration on its absence.

1 files changed, 11 insertions, 5 deletions

diff --git a/R/api.R b/R/api.R
index 0d13c67..895c52a 100644
--- a/R/api.R
+++ b/R/api.R
@@ -13,7 +13,10 @@
 #' @section Conditions:
 #' \describe{
 #'   \item{`cepis_invalid_cep`}{the CEP is not 8 digits. No request is made.}
-#'   \item{`cepis_not_found`}{well-formed, but not in the database.}
+#'   \item{`cepis_not_found`}{well-formed, but not in the database. Carries
+#'     `faixa`, a [cepis_faixa] naming the municipality whose range the CEP
+#'     fell into, when it fell into one. Still a not-found: the CEP does not
+#'     exist, and a `faixa` is not an address.}
 #'   \item{`cepis_rate_limited`}{429 on every attempt.}
 #'   \item{`cepis_server_error`}{5xx on every attempt.}
 #'   \item{`cepis_network_error`}{the request never completed.}
@@ -38,10 +41,13 @@ cep_lookup <- function(cep, client = default_client()) {
   response <- cepis_fetch(client, paste0("/", number))
 
   if (response$status == 404L) {
-    stop(not_found_error(
-      paste0("CEP ", number, " does not exist in the DNE database"),
-      cep = number
-    ))
+    faixa <- new_faixa(json_field(response$body, "faixa"))
+    message <- paste0("CEP ", number, " does not exist in the DNE database")
+    if (!is.null(faixa)) {
+      message <- paste0(message, "; the range it falls in belongs to ",
+                        faixa$localidade, "/", faixa$uf)
+    }
+    stop(not_found_error(message, cep = number, faixa = faixa))
   }
   if (response$status == 400L) {
     stop(invalid_cep_error(