Carry the municipality a missing CEP would belong toHEADv0.2.0main

A 404 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 to the
not-found body naming the municipality that owns the range, so the caller
can say "no such CEP, but that range is Areal/RJ" instead of only "no".

It stays an error. Faixa hangs off CepNotFoundException, never off
Address, and parsing is deliberately lenient: an absent, malformed or
unnamed block yields a null Nullable, so reading the extra context can
never cost the caller the answer it already had.

cep_ini and cep_fim are the smallest and largest CEP that actually exist
there, not the bounds the Correios publish, and the range between them is
sparse — hence ceps, so nobody mistakes the pair for a list.

1 files changed, 4 insertions, 0 deletions

diff --git a/source/cepis/package.d b/source/cepis/package.d
index 073d377..9a8c433 100644
--- a/source/cepis/package.d
+++ b/source/cepis/package.d
@@ -41,6 +41,10 @@
  *     if (error.retriable) reschedule(); // network, server, rate limit
  * ---
  *
+ * A not-found sometimes knows where the CEP $(I would) have been — see
+ * $(D CepNotFoundException.faixa) and $(D Faixa). That is context for the
+ * error, never an address.
+ *
  * Note on field names: the API surface is English, but the $(B data fields keep
  * the API's own Portuguese names) ($(D logradouro), $(D bairro),
  * $(D localidade)). What you read in the JSON is what you access on the value.