1 files changed, 40 insertions, 4 deletions
diff --git a/src/Cepis/CepNotFoundException.cs b/src/Cepis/CepNotFoundException.cs
index ced7b16..19a4576 100644
--- a/src/Cepis/CepNotFoundException.cs
+++ b/src/Cepis/CepNotFoundException.cs
@@ -4,24 +4,60 @@ namespace Cepis;
 /// The CEP is well-formed but does not exist in the DNE database.
 /// </summary>
 /// <remarks>
+/// <para>
 /// Retrying does not help: the answer is definitive until the next fortnightly
 /// database. A batch never throws this — a CEP with no address is
 /// <see langword="null"/> at its position instead.
+/// </para>
+/// <para>
+/// <see cref="Faixa"/> carries the municipality the CEP would have belonged to,
+/// when the API can name one. It is context for the failure and not a fallback
+/// address: this is still a 404.
+/// </para>
 /// </remarks>
 public sealed class CepNotFoundException : CepisException
 {
-    /// <summary>Create the exception with a message.</summary>
+    /// <summary>Create the exception with a message and the range, if any.</summary>
     /// <param name="message">what went wrong</param>
-    public CepNotFoundException(string message)
+    /// <param name="faixa">
+    /// the municipality the CEP would belong to, or <see langword="null"/> when
+    /// the API named none
+    /// </param>
+    public CepNotFoundException(string message, Faixa? faixa = null)
         : base(message)
     {
+        Faixa = faixa;
     }
 
-    /// <summary>Create the exception with a message and an underlying cause.</summary>
+    /// <summary>Create the exception with a message, the range and a cause.</summary>
     /// <param name="message">what went wrong</param>
+    /// <param name="faixa">the municipality the CEP would belong to, if any</param>
     /// <param name="innerException">the failure underneath</param>
-    public CepNotFoundException(string message, Exception? innerException)
+    public CepNotFoundException(string message, Faixa? faixa, Exception? innerException)
         : base(message, innerException)
     {
+        Faixa = faixa;
     }
+
+    /// <summary>
+    /// The municipality the CEP would have belonged to, or
+    /// <see langword="null"/> when there is none.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <see langword="null"/> is the ordinary case for a CEP falling in a band
+    /// no municipality owns: the API <b>omits</b> the block rather than sending
+    /// a null, and an older API does not send it at all. Anything unreadable in
+    /// it lands here as <see langword="null"/> too — a courtesy field is not
+    /// worth turning a clean not-found into a parse error over.
+    /// </para>
+    /// <para>
+    /// It says which municipality the number <i>would</i> be in, not that any
+    /// address exists. Read <see cref="Cepis.Faixa"/> before using
+    /// <see cref="Cepis.Faixa.CepIni"/> and <see cref="Cepis.Faixa.CepFim"/>:
+    /// they bound the CEPs that exist there, and the range between them is
+    /// mostly empty.
+    /// </para>
+    /// </remarks>
+    public Faixa? Faixa { get; }
 }