ApiBrasil.Core.Error exception (APIBrasil v0.0.1)

Copy Markdown View Source

Erro devolvido por todas as chamadas da SDK.

Toda função devolve {:ok, resultado} ou {:error, %ApiBrasil.Core.Error{}}, e a falha carrega a categoria em :kind — o equivalente Elixir às subclasses de erro das demais SDKs da plataforma.

case ApiBrasil.Data.Consulta.cpf(client, %{"cpf" => "00000000000"}) do
  {:ok, consulta} ->
    ApiBrasil.Core.CreditResponse.data(consulta)

  {:error, %ApiBrasil.Core.Error{kind: :insufficient_balance}} ->
    IO.puts("Recarregue seus créditos")

  {:error, %ApiBrasil.Core.Error{kind: :rate_limit} = error} ->
    IO.puts("Aguarde #{error.retry_after}ms")

  {:error, error} ->
    IO.puts(Exception.message(error))
end

As variantes ! (ex: cpf!/3) levantam este erro em vez de devolver a tupla.

Summary

Types

kind()

Categoria da falha.

t()

Functions

api?(error)

Falha genérica da API.

authentication(message, fields \\ [])

Falha de autenticação.

authentication?(error)

HTTP 401 — token ausente, inválido ou expirado.

from_api(status, body, headers \\ %{})

Mapeia um status HTTP + corpo de erro para o erro adequado, replicando a hierarquia de erros das demais SDKs.

header(headers, name)

Lê um header sem diferenciar maiúsculas de minúsculas.

insufficient_balance?(error)

HTTP 402 — saldo/créditos insuficientes.

kind_for_status(status)

Categoria correspondente a um status HTTP.

kinds()

Lista todas as categorias de erro.

network(message, fields \\ [])

Falha de rede — nenhuma resposta recebida.

network?(error)

Falha antes da resposta — rede ou tempo limite.

new(kind, message, fields \\ [])

Cria um erro da categoria informada.

not_found?(error)

HTTP 404/410 — não encontrado ou desativado.

parse_retry_after(headers, now \\ nil)

Lê o header Retry-After — segundos ou data HTTP (IMF-fixdate) — e devolve a espera em milissegundos.

permission?(error)

HTTP 403 — sem permissão.

rate_limit?(error)

HTTP 429 — rate limit atingido.

server?(error)

HTTP 5xx — erro interno do gateway/provedor.

timeout(message, fields \\ [])

Falha por tempo limite excedido.

timeout?(error)

Tempo limite excedido.

validation(message, fields \\ [])

Falha de validação (payload inválido).

validation?(error)

HTTP 400/422 — payload inválido.

Types

kind()

@type kind() ::
  :api
  | :network
  | :timeout
  | :validation
  | :authentication
  | :insufficient_balance
  | :permission
  | :not_found
  | :rate_limit
  | :server

Categoria da falha.

  • :api — falha genérica da API;
  • :network — falha de rede, a requisição pode não ter chegado ao servidor;
  • :timeout — tempo limite excedido (nunca refeito automaticamente);
  • :validation — HTTP 400/422, payload inválido;
  • :authentication — HTTP 401, Bearer Token ausente, inválido ou expirado;
  • :insufficient_balance — HTTP 402, saldo/créditos insuficientes;
  • :permission — HTTP 403, sem permissão (ex: API exige conta PJ);
  • :not_found — HTTP 404/410, recurso não encontrado ou desativado;
  • :rate_limit — HTTP 429, limite de requisições atingido;
  • :server — HTTP 5xx, erro interno do gateway/provedor.

t()

@type t() :: %ApiBrasil.Core.Error{
  __exception__: true,
  code: String.t() | nil,
  kind: kind(),
  message: String.t(),
  reason: term(),
  response: term(),
  retry_after: non_neg_integer() | nil,
  status: pos_integer() | nil
}

Functions

api?(error)

@spec api?(t()) :: boolean()

Falha genérica da API.

authentication(message, fields \\ [])

@spec authentication(
  String.t(),
  keyword()
) :: t()

Falha de autenticação.

authentication?(error)

@spec authentication?(t()) :: boolean()

HTTP 401 — token ausente, inválido ou expirado.

from_api(status, body, headers \\ %{})

@spec from_api(pos_integer(), term(), map()) :: t()

Mapeia um status HTTP + corpo de erro para o erro adequado, replicando a hierarquia de erros das demais SDKs.

header(headers, name)

@spec header(map(), String.t()) :: String.t() | nil

Lê um header sem diferenciar maiúsculas de minúsculas.

insufficient_balance?(error)

@spec insufficient_balance?(t()) :: boolean()

HTTP 402 — saldo/créditos insuficientes.

kind_for_status(status)

@spec kind_for_status(pos_integer()) :: kind()

Categoria correspondente a um status HTTP.

kinds()

@spec kinds() :: [kind()]

Lista todas as categorias de erro.

network(message, fields \\ [])

@spec network(
  String.t(),
  keyword()
) :: t()

Falha de rede — nenhuma resposta recebida.

network?(error)

@spec network?(t()) :: boolean()

Falha antes da resposta — rede ou tempo limite.

new(kind, message, fields \\ [])

@spec new(kind(), String.t(), keyword()) :: t()

Cria um erro da categoria informada.

not_found?(error)

@spec not_found?(t()) :: boolean()

HTTP 404/410 — não encontrado ou desativado.

parse_retry_after(headers, now \\ nil)

@spec parse_retry_after(map(), integer() | nil) :: non_neg_integer() | nil

Lê o header Retry-After — segundos ou data HTTP (IMF-fixdate) — e devolve a espera em milissegundos.

permission?(error)

@spec permission?(t()) :: boolean()

HTTP 403 — sem permissão.

rate_limit?(error)

@spec rate_limit?(t()) :: boolean()

HTTP 429 — rate limit atingido.

server?(error)

@spec server?(t()) :: boolean()

HTTP 5xx — erro interno do gateway/provedor.

timeout(message, fields \\ [])

@spec timeout(
  String.t(),
  keyword()
) :: t()

Falha por tempo limite excedido.

timeout?(error)

@spec timeout?(t()) :: boolean()

Tempo limite excedido.

validation(message, fields \\ [])

@spec validation(
  String.t(),
  keyword()
) :: t()

Falha de validação (payload inválido).

validation?(error)

@spec validation?(t()) :: boolean()

HTTP 400/422 — payload inválido.