From 82d92ed4291663bae94014b4363064dbb26c6a51 Mon Sep 17 00:00:00 2001
From: Murilo Ijanc <murilo@ijanc.org>
Date: Mon, 27 Jul 2026 20:25:04 -0300
Subject: Name the municipality behind a CEP that does not exist
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A CEP that fails a lookup is rarely a random number: it is usually someone
who knows the city and guessed the digits, and the classic guess is the
-000 that 957 municipalities never received. The API now attaches a faixa
block to the 404 naming the municipality that band belongs to, so the
caller can answer "no, but you were looking at Areal/RJ" instead of just
"no".

It stays an error. Faixa hangs off CepNotFoundException, never off Address,
and cepIni/cepFim are the extremes that actually exist in the municipality
rather than the range the Correios publish — echoing back the published
start would return the very CEP that just failed. The interval is sparse,
which is what ceps is for; it is not a list of alternatives.

Parsing is deliberately forgiving: a missing, empty or malformed block is
null. Losing a clean not-found to a parse error over the hint attached to
it would be a bad trade.
---
 README.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

(limited to 'README.md')

diff --git a/README.md b/README.md
index ffb4cac..1f4518a 100644
--- a/README.md
+++ b/README.md
@@ -204,6 +204,48 @@ try {
 `RateLimitedException` exposes `retryAfter`, `ServerException` exposes `status`,
 and `NetworkException` exposes `cause`.
 
+### When the CEP does not exist
+
+A failing CEP is rarely random: it is usually someone who knows the city and
+guessed the number — and the classic guess is the `-000`, which 957
+municipalities never received. So `CepNotFoundException` may carry a `faixa`
+naming the municipality the CEP *would* have belonged to:
+
+```dart
+try {
+  final address = await cepis.lookup('25845-000');
+} on cepis.CepNotFoundException catch (e) {
+  final faixa = e.faixa;
+  if (faixa != null) {
+    faixa.localidade; // 'Areal'
+    faixa.uf;         // 'RJ'
+    faixa.ibge;       // '3300225'
+    faixa.cepIni;     // '25845001'  (the API's `cep_ini`)
+    faixa.cepFim;     // '25849899'  (the API's `cep_fim`)
+    faixa.ceps;       // 118
+  }
+}
+```
+
+Three things this is not:
+
+- **Not an address.** The response is still a 404 and the CEP still does not
+  exist. `faixa` is context for the error — enough to say "did you mean somewhere
+  in Areal/RJ?" — and never a value to save as the user's address.
+- **Not the Correios' published range.** `cepIni` and `cepFim` are the smallest
+  and the largest CEP that *actually exist* in the municipality. The DNE's own
+  start for Areal is `25845000` — exactly the CEP that just failed, which is why
+  echoing it back would be useless.
+- **Not a range of valid CEPs.** It is sparse: Areal's 118 CEPs are scattered
+  over the ~9000 numbers between the two bounds. That is what `ceps` is for. Do
+  not iterate the interval and do not offer it as a list of alternatives.
+
+`faixa` is `null` when the CEP falls in a numeric band no municipality owns — the
+API **omits** the block there rather than sending null — and also whenever the
+block cannot be read. A malformed one never costs you the clean not-found.
+
+`e.toString()` mentions the municipality when there is one.
+
 `InvalidCepException` also implements `FormatException`, so code already
 handling malformed input during validation keeps working without knowing this
 library exists.
-- 
cgit v1.3