1 files changed, 29 insertions, 8 deletions
diff --git a/lib/Cepis/Error.pm b/lib/Cepis/Error.pm
index 080b0a1..37f2a08 100644
--- a/lib/Cepis/Error.pm
+++ b/lib/Cepis/Error.pm
@@ -3,7 +3,7 @@ package Cepis::Error;
 use strict;
 use warnings;
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 use overload
     '""'     => sub { $_[0]->message },
@@ -30,7 +30,7 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 package Cepis::Error::CEPNotFound;
 
@@ -38,7 +38,9 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
+
+sub faixa { return $_[0]->{faixa} }
 
 package Cepis::Error::Network;
 
@@ -46,7 +48,7 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 package Cepis::Error::ServerError;
 
@@ -54,7 +56,7 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 sub status { return $_[0]->{status} }
 
@@ -64,7 +66,7 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 sub retry_after { return $_[0]->{retry_after} }
 
@@ -74,7 +76,7 @@ use strict;
 use warnings;
 use parent -norequire, 'Cepis::Error';
 
-our $VERSION = '0.1.0';
+our $VERSION = '0.2.0';
 
 1;
 
@@ -171,6 +173,25 @@ message.
 
 The CEP is well-formed but does not exist in the DNE database.
 
+=over 4
+
+=item C<< $err->faixa >>
+
+A L<Cepis::Faixa> naming the municipality the CEP I<would> belong to, or
+C<undef> when it fell in a band no municipality owns. The API omits the block
+rather than sending null, and a malformed one is dropped rather than turning the
+not-found into a parse failure.
+
+It is context for the error, B<not> an address: the lookup still failed. What it
+buys is telling the user "25845000 does not exist in Areal/RJ" instead of "not
+found" — worth having, because a failing CEP is rarely random. It is usually
+someone who knows the city and guessed the number, and the classic guess is the
+C<-000> that 957 municipalities never received.
+
+When it is present, the message already names the municipality.
+
+=back
+
 =head2 Cepis::Error::Network
 
 The request never completed: DNS, refused connection, timeout, TLS.
@@ -217,7 +238,7 @@ as a diagnosis: the problem is not in your code.
 
 =head1 SEE ALSO
 
-L<Cepis>, L<Cepis::Client>
+L<Cepis>, L<Cepis::Client>, L<Cepis::Faixa>
 
 =head1 LICENCE