From 58dbe934a90c1eda8e76cd218a413f01a4d9b11d Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:33:25 -0300 Subject: Carry the municipality of a missing CEP on not_found MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A CEP that fails is rarely a random number: it is someone who knows the city and guessed the digits, and the classic guess is the -000 that 957 municipalities never received. The API now answers that 404 with an optional faixa block naming where the CEP would have been, so a caller can turn "CEP does not exist" into something the user can act on. It hangs off the error, never off an address: the lookup still failed. Parsing gives up quietly at every step — no block, a block that is not an object, one without a municipality to name — because a broken piece of context must not turn a clean not-found into a parse failure. cep_ini and cep_fim are the CEPs that exist, not the range the Correios publish, and the interval between them is sparse; ceps is what keeps the pair from being read as a list of valid CEPs. --- cepis/errors.lua | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) (limited to 'cepis/errors.lua') diff --git a/cepis/errors.lua b/cepis/errors.lua index 0076b95..011014b 100644 --- a/cepis/errors.lua +++ b/cepis/errors.lua @@ -27,6 +27,12 @@ local M = {} M.INVALID_CEP = "invalid_cep" --- The CEP is well-formed but does not exist in the DNE database. +-- +-- The error may carry `faixa`, a `cepis.models.Faixa` naming the municipality +-- that CEP would have belonged to. It is context for the failure, never an +-- address: the lookup failed all the same. It is `nil` when the CEP falls in a +-- band no municipality owns — the API omits the block there rather than +-- sending null. M.NOT_FOUND = "not_found" --- The API (or the edge in front of it) answered 429 on every attempt. @@ -88,7 +94,8 @@ M.Error = Error -- -- @tparam string kind one of the six constants in this module -- @tparam string message human-readable, already complete --- @tparam[opt] table fields extra context: `cep`, `status`, `retry_after` +-- @tparam[opt] table fields extra context: `cep`, `status`, `retry_after`, +-- `faixa` -- @treturn table the error, with `tostring()` yielding `message` function M.new(kind, message, fields) local err = setmetatable({}, Error) -- cgit v1.3