!> Status codes returned by every fallible procedure in this library.
!>
!> Fortran has no exceptions, so every call that can fail takes an
!> `integer, intent(out) :: status` and a
!> `character(len=:), allocatable, intent(out) :: message`. `status` is one of
!> the parameters below; `message` is always allocated, and is the empty string
!> on success.
!>
!> The split is by **the decision the caller has to make**, not by the HTTP
!> status that caused it. `CEPIS_ERR_INVALID_CEP` and `CEPIS_ERR_NOT_FOUND` are
!> problems with the request: retrying returns the same answer more slowly. The
!> three transport errors below them may succeed later, and the client already
!> retried on its own before returning any of them.
module cepis_errors
    implicit none
    private

    !> The call succeeded.
    integer, parameter, public :: CEPIS_OK = 0

    !> The CEP is not 8 digits, or the API rejected it with a 400.
    !>
    !> Usually returned without any request being made: the client validates
    !> the format before going to the network.
    integer, parameter, public :: CEPIS_ERR_INVALID_CEP = 1

    !> The CEP is well-formed but does not exist in the DNE database.
    integer, parameter, public :: CEPIS_ERR_NOT_FOUND = 2

    !> The API answered 429 on every attempt. `retry_after` carries what the
    !> server asked for, in seconds, or a negative value when it did not say.
    integer, parameter, public :: CEPIS_ERR_RATE_LIMITED = 3

    !> The API answered 5xx on every attempt. `http_status` carries the status
    !> seen on the last attempt.
    integer, parameter, public :: CEPIS_ERR_SERVER = 4

    !> The request never completed: DNS, refused connection, timeout, TLS.
    integer, parameter, public :: CEPIS_ERR_NETWORK = 5

    !> A success status came back with a body that cannot be parsed.
    !>
    !> In practice something between the caller and the API is answering
    !> instead of it: a captive Wi-Fi portal, a corporate proxy, an HTML error
    !> page.
    integer, parameter, public :: CEPIS_ERR_INVALID_RESPONSE = 6

    !> A configuration value is out of range. Not one of the six categories
    !> above: it is a programming error, caught before any request is made.
    integer, parameter, public :: CEPIS_ERR_CONFIG = 7

    public :: cepis_status_name

contains

    !> A short, stable, English name for a status code.
    pure function cepis_status_name(status) result(name)
        integer, intent(in) :: status
        character(len=:), allocatable :: name

        select case (status)
        case (CEPIS_OK)
            name = 'ok'
        case (CEPIS_ERR_INVALID_CEP)
            name = 'invalid_cep'
        case (CEPIS_ERR_NOT_FOUND)
            name = 'not_found'
        case (CEPIS_ERR_RATE_LIMITED)
            name = 'rate_limited'
        case (CEPIS_ERR_SERVER)
            name = 'server_error'
        case (CEPIS_ERR_NETWORK)
            name = 'network_error'
        case (CEPIS_ERR_INVALID_RESPONSE)
            name = 'invalid_response'
        case (CEPIS_ERR_CONFIG)
            name = 'config_error'
        case default
            name = 'unknown'
        end select
    end function cepis_status_name

end module cepis_errors