BankingCircle.Error exception (banking_circle v1.0.0)

Copy Markdown View Source

Canonical error representation for every failure mode this client can surface: transport failures, HTTP 4xx/5xx responses (in either of Banking Circle's two documented error body shapes), auth failures, and client-side validation errors raised before a request is ever sent.

Banking Circle returns two distinct error body shapes depending on the endpoint family:

  • Standard operations (e.g. single payments):

    %{"propertyName" => _, "errorCode" => _, "errorDescription" => _}

  • Bulk operations (e.g. bulk payment initiation), one entry per row:

    %{"fieldIndex" => _, "elementIndex" => _, "errorCode" => _, "errorDescription" => _}

parse/2 normalizes both into detail/0 so callers never need to branch on which shape came back.

Summary

Types

detail()
kind()
t()

Functions

parse(status, body, opts \\ [])

Parses an HTTP response (status + body) into a t/0, normalizing either documented error body shape and classifying the failure kind from the status code.

retryable?(error)

True if the error kind is generally safe to retry (429 and 5xx).

timeout(timeout_ms)
transport_error(reason)

Builds a transport-level error (connection reset, DNS failure, etc.).

Types

detail()

@type detail() :: %{
  optional(:property_name) => String.t() | nil,
  optional(:field_index) => integer() | nil,
  optional(:element_index) => integer() | nil,
  code: String.t() | nil,
  description: String.t() | nil
}

kind()

@type kind() ::
  :transport_error
  | :timeout
  | :auth_error
  | :validation_error
  | :rate_limited
  | :concurrency_conflict
  | :not_found
  | :client_error
  | :server_error
  | :unexpected_response

t()

@type t() :: %BankingCircle.Error{
  __exception__: true,
  details: [detail()],
  kind: kind(),
  message: String.t(),
  raw_body: term(),
  request_id: String.t() | nil,
  retry_after_ms: non_neg_integer() | nil,
  status: pos_integer() | nil
}

Functions

parse(status, body, opts \\ [])

@spec parse(pos_integer(), term(), keyword()) :: t()

Parses an HTTP response (status + body) into a t/0, normalizing either documented error body shape and classifying the failure kind from the status code.

retryable?(error)

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

True if the error kind is generally safe to retry (429 and 5xx).

timeout(timeout_ms)

@spec timeout(pos_integer()) :: t()

transport_error(reason)

@spec transport_error(term()) :: t()

Builds a transport-level error (connection reset, DNS failure, etc.).