Carry the municipality of a CEP that does not existHEADv0.2.0main

A 404 that only says "not found" is correct and useless. The CEP that
fails is almost never random: it is someone who knows the city and
guessed the number, and the classic guess is the -000 that 957
municipalities never received.

The API now names the municipality on the 404, so surface it as
Error.Faixa instead of throwing the body away.

1 files changed, 16 insertions, 0 deletions

diff --git a/errors.go b/errors.go
index 98a2385..08f909a 100644
--- a/errors.go
+++ b/errors.go
@@ -84,6 +84,22 @@ type Error struct {
 	// the client's own cap is applied to it.
 	RetryAfter time.Duration
 
+	// Faixa is the municipality the CEP would belong to, set only on
+	// [ErrCEPNotFound] and only when the API could name one. It is nil for
+	// every other kind, and also for a CEP that falls in a numeric band the
+	// Correios never handed to any municipality.
+	//
+	// It turns "this CEP does not exist" into something the caller can act
+	// on: the city is right, the number is not.
+	//
+	//	var cerr *cepis.Error
+	//	if errors.As(err, &cerr) && cerr.Faixa != nil {
+	//	        fmt.Printf("did you mean somewhere in %s/%s? (%s to %s)\n",
+	//	                cerr.Faixa.Localidade, cerr.Faixa.UF,
+	//	                cerr.Faixa.CEPIni, cerr.Faixa.CEPFim)
+	//	}
+	Faixa *Faixa
+
 	// Message describes the failure without the "cepis: " prefix.
 	Message string