From 399eac351b1bc29d5047dbac96486c281be1b05c Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:38:27 -0300 Subject: Report the municipality a missing CEP would have belonged to 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. --- R/api.R | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) (limited to 'R/api.R') 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( -- cgit v1.3