diff options
| author | Murilo Ijanc <[email protected]> | 2026-07-27 20:33:25 -0300 |
|---|---|---|
| committer | Murilo Ijanc <[email protected]> | 2026-07-27 20:33:25 -0300 |
| commit | 58dbe934a90c1eda8e76cd218a413f01a4d9b11d (patch) | |
| tree | deaee88adad3791c8f010db7f7161a95318ed67e /cepis/errors.lua | |
| parent | 7fd555fcaf4304cb0dff3e8f5661565c3618299e (diff) | |
| download | lua-f240a59e24e41bf5c7e533d66ed5cad4f2f293d8.tar.gz | |
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.
Diffstat (limited to 'cepis/errors.lua')
| -rw-r--r-- | cepis/errors.lua | 9 |
1 files changed, 8 insertions, 1 deletions
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) |