Name the municipality behind a CEP that does not existHEADv0.2.0main

A CEP that fails 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. Answering that with a bare "not
found" throws away what the API already knows: which municipality the
number would have fallen under.

The 404 now carries an optional faixa, and it is exposed the way geo
already is — a derived type behind a logical flag on the address, because
the API omits the block entirely rather than sending null. It stays a
404: found is still false and the status is still CEPIS_ERR_NOT_FOUND.
The band is context for the failure, never an address.

cep_ini and cep_fim are the smallest and largest CEP that actually exist
there, not the bounds the Correios publish — the published start for
Areal is 25845000, exactly the CEP that fails. The pair is not a list
either: 118 CEPs over some 4,900 numbers, which is what ceps is for.

Parsing is deliberately silent about every failure. A body that is not
JSON, or a faixa that is absent, null, not an object or empty, leaves
has_faixa false. Turning any of those into an invalid-response error
would tell the caller to retry a CEP that will never exist.

1 files changed, 14 insertions, 0 deletions

diff --git a/app/main.f90 b/app/main.f90
index 5e3f988..0029d6e 100644
--- a/app/main.f90
+++ b/app/main.f90
@@ -109,6 +109,7 @@ contains
         call handle%lookup(cep, address, code, detail)
         if (code /= CEPIS_OK) then
             write (error_unit, '(A)') 'cepis: '//cepis_status_name(code)//': '//detail
+            if (address%has_faixa) call show_faixa(address%faixa)
             stop 1
         end if
 
@@ -132,6 +133,19 @@ contains
         end if
     end subroutine show_one
 
+    !> What the API knows about a CEP that does not exist: the municipality it
+    !> would have fallen under. The lookup still failed, so this goes to stderr
+    !> with the error, and the exit status stays 1.
+    subroutine show_faixa(faixa)
+        type(cepis_faixa), intent(in) :: faixa
+
+        write (error_unit, '(A)') '  faixa        '//faixa%localidade//'/'// &
+            faixa%uf//'  ibge '//faixa%ibge
+        write (error_unit, '(A,I0,A)') '  existentes   '//faixa%formatted_cep_ini()// &
+            '..'//faixa%formatted_cep_fim()//'  ', faixa%ceps, &
+            ' CEPs (the range is sparse; most numbers in it do not exist)'
+    end subroutine show_faixa
+
     subroutine show_many(handle, values)
         type(cepis_client), intent(in) :: handle
         character(len=*), intent(in) :: values(:)