diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 41 |
1 files changed, 41 insertions, 0 deletions
@@ -192,6 +192,47 @@ try { `RateLimited` exposes `retryAfterMs` and `ServerError` exposes `status`. +### When the CEP does not exist + +`CEPNotFound` may carry a `faixa`: the municipality the CEP _would_ belong to. +A failing CEP is rarely random — it is someone who knows the city and guessed +the number, and the classic guess is the `-000` that 957 municipalities never +received. + +```ts +import { CEPNotFound, lookup } from "cepis"; + +try { + await lookup("25845000"); +} catch (error) { + if (error instanceof CEPNotFound && error.faixa) { + error.faixa.localidade; // "Areal" + error.faixa.uf; // "RJ" + error.faixa.ibge; // "3300225" + error.faixa.cep_ini; // "25845001" + error.faixa.cep_fim; // "25849899" + error.faixa.ceps; // 118 + error.faixa.label; // "Areal/RJ" + } +} +``` + +Three things about it: + +- **It is still a 404.** `faixa` is context for the error, never an address. + Showing "did you mean a CEP in Areal/RJ?" is the point; treating it as a + result is a wrong delivery. +- **`cep_ini`/`cep_fim` are the CEPs that actually exist there**, not the range + the Correios publish. The DNE's own start for Areal is `25845000` — exactly + the CEP that just failed. +- **The range is sparse.** Areal's 118 CEPs are scattered across the ~4,900 + numbers between `25845001` and `25849899`. That is what `ceps` is for: the + pair is not a list of valid CEPs, and iterating it yields mostly 404s. + +When the CEP falls in a band no municipality owns, the API **omits** the field +and `error.faixa` is `undefined` — never `null`. A missing or unreadable +`faixa` never turns a clean not-found into a parse failure. + `InvalidResponse` almost always means something between you and the API is answering instead of it — a captive Wi-Fi portal, a corporate proxy, an HTML error page. Useful as a diagnosis: the problem is not in your code. |