From 4ebb31f26efed74f8fcb049fe27ddf7cf5388a08 Mon Sep 17 00:00:00 2001
From: Murilo Ijanc <murilo@ijanc.org>
Date: Mon, 27 Jul 2026 20:31:55 -0300
Subject: Carry the municipality of a CEP that does not exist

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 the 404 with the
municipality that band belongs to, which is enough to tell the user
"Areal/RJ, but not that number" instead of a bare failure.

It stays an error. Faixa hangs off CEPNotFound rather than becoming a
result, cep_ini/cep_fim are documented as the CEPs that exist there and
not as a range to iterate, and an absent or unreadable block yields
undefined so that context can never cost the caller the clean not-found
it was already getting.
---
 src/errors.ts | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

(limited to 'src/errors.ts')

diff --git a/src/errors.ts b/src/errors.ts
index 4e5dbb2..1a1e267 100644
--- a/src/errors.ts
+++ b/src/errors.ts
@@ -20,6 +20,8 @@
  * @module
  */
 
+import type { Faixa } from "./models.js";
+
 /**
  * Base of every error this library throws. Catch it to handle any failure.
  *
@@ -52,15 +54,29 @@ export class InvalidCEP extends CepisError {
  *
  * Never thrown by {@link Client.lookupMany}, which reports a missing CEP as
  * `null` at its position instead.
+ *
+ * `faixa` says which municipality the CEP *would* belong to, when the number
+ * falls inside a band some municipality owns. It is context for the failure and
+ * nothing more — this is still a 404, and the CEP still does not exist.
  */
 export class CEPNotFound extends CepisError {
   /** The 8-digit CEP that was looked up. */
   readonly cep: string;
+  /**
+   * The municipality the CEP would have belonged to, or `undefined` when it
+   * falls in a band no municipality owns.
+   *
+   * Read {@link Faixa} before using it: `cep_ini`/`cep_fim` are the CEPs that
+   * exist there, the range between them is sparse, and none of it makes the
+   * looked-up CEP valid.
+   */
+  readonly faixa?: Faixa;
 
-  constructor(message: string, cep: string, options?: ErrorOptions) {
+  constructor(message: string, cep: string, faixa?: Faixa, options?: ErrorOptions) {
     super(message, options);
     this.name = "CEPNotFound";
     this.cep = cep;
+    this.faixa = faixa;
   }
 }
 
-- 
cgit v1.3