Bourse.Error exception (bourse v0.1.0)

Unified error types for exchange operations.

All exchange errors are normalized to this struct, providing consistent error handling across every configured exchange. Each error carries its type, the original exchange error code and message, recoverability, and the upstream retry classification bucket.

Error Types

Recoverable (can retry automatically)

:rate_limit_exceeded - Too many requests, retry after retry_after ms
:network_error - Connection or timeout issue
:exchange_not_available - Exchange down, on maintenance, or market closed

Non-recoverable (require intervention)

:authentication_error - API key/secret rejected or invalid nonce
:insufficient_funds - Not enough funds for the operation
:invalid_order - Order parameters rejected by exchange
:order_not_found - Order ID does not exist
:bad_request - Invalid request parameters
:bad_symbol - Symbol not recognized by exchange
:permission_denied - API key lacks permissions or account suspended
:access_restricted - Geographic/IP block or wrong-URL HTML response (non-Cloudflare)
:cloudflare_challenge - Cloudflare anti-bot challenge page (exchange reachable but requires browser/approved client)
:not_supported - Method not supported by this exchange
:operation_failed - Operation rejected or failed
:invalid_parameters - Invalid request parameters (code bug)
:market_closed - Market is not currently trading
:circuit_open - Circuit breaker tripped due to consecutive failures

Generic

:exchange_error - Unmapped error (see code and message)

Example

case Bourse.HTTP.request(exchange, :post, "/v5/order/create", params: params) do
  {:ok, response} -> handle_response(response)
  {:error, %Bourse.Error{type: :insufficient_funds}} -> notify_low_balance()
  {:error, %Bourse.Error{type: :rate_limit_exceeded, retry_after: ms}} -> Process.sleep(ms)
  {:error, %Bourse.Error{} = err} -> Logger.error("Exchange error: #{err.message}")
end

Summary

Types

error_type()

retry_class()

Upstream (Bourse Phase 13) retry classification bucket for an error.

t()

Functions

access_restricted(opts \\ [])

Creates an access restricted error.

authentication_error(opts \\ [])

Creates an authentication error.

bad_request(opts \\ [])

Creates a bad request error.

bad_symbol(opts \\ [])

Creates a bad symbol error.

circuit_open(opts \\ [])

Creates a circuit breaker open error.

cloudflare_challenge(opts \\ [])

Creates a Cloudflare challenge error.

exchange_error(message, opts \\ [])

Creates a generic exchange error.

exchange_not_available(opts \\ [])

Creates an exchange not available error.

from_spec_class(class_name)

Maps a Bourse spec exception class to an error type atom.

from_spec_class(class_name, ancestors)

Maps a Bourse spec exception class to an error type, walking the upstream class hierarchy when the class is not directly mapped.

insufficient_funds(opts \\ [])

Creates an insufficient funds error.

invalid_order(opts \\ [])

Creates an invalid order error.

invalid_parameters(opts \\ [])

Creates an invalid parameters error.

market_closed(opts \\ [])

Creates a market closed error.

network_error(opts \\ [])

Creates a network error.

non_recoverable_types()

Returns all non-recoverable error types.

not_supported(opts \\ [])

Creates a not supported error.

operation_failed(opts \\ [])

Creates an operation failed error.

order_not_found(opts \\ [])

Creates an order not found error.

permission_denied(opts \\ [])

Creates a permission denied error.

rate_limit_exceeded(opts \\ [])

Creates a rate limit exceeded error.

recoverable?(type)

Returns the recoverability classification for an error type.

recoverable_types()

Returns all recoverable error types.

retry_class(type)

Returns the canonical retry classification bucket for an error type.

retry_class_mapping()

Returns the canonical error_type → retry bucket map.

should_retry?(class)

Returns whether an error (or retry bucket) is worth retrying.

spec_class_mapping()

Returns the full spec class to error type mapping.

Types

error_type()

@type error_type() ::
  :rate_limit_exceeded
  | :network_error
  | :exchange_not_available
  | :authentication_error
  | :insufficient_funds
  | :invalid_order
  | :order_not_found
  | :bad_request
  | :bad_symbol
  | :permission_denied
  | :access_restricted
  | :cloudflare_challenge
  | :not_supported
  | :operation_failed
  | :invalid_parameters
  | :market_closed
  | :circuit_open
  | :exchange_error

retry_class()

@type retry_class() ::
  :rate_limit | :network | :server_busy | :auth | :non_retryable | nil

Upstream (Bourse Phase 13) retry classification bucket for an error.

Adopted from the v4 spec's errors.retry_classification. Refines the coarse recoverable? boolean into the canonical retry semantics:

:rate_limit — back off and retry (handled by the rate limiter)
:network — transient connectivity/timeout; safe to retry
:server_busy — exchange unavailable/maintenance; safe to retry
:auth — credential/permission failure; do not retry without intervention
:non_retryable — deterministic rejection (bad params, no funds, …)
nil — unclassified (generic exchange_error)

t()

@type t() :: %Bourse.Error{
  __exception__: term(),
  code: String.t() | integer() | nil,
  exchange: String.t() | nil,
  hints: [String.t()],
  http_status: non_neg_integer() | nil,
  message: String.t(),
  raw: map() | binary() | nil,
  recoverable: boolean() | nil,
  retry_after: non_neg_integer() | nil,
  retry_class: retry_class(),
  type: error_type()
}

Functions

access_restricted(opts \\ [])

@spec access_restricted(keyword()) :: t()

Creates an access restricted error.

Used when exchange returns HTML instead of JSON without Cloudflare markers — typically a wrong URL/prefix, geo/IP block, or landing page. Cloudflare challenges use cloudflare_challenge/1 instead.

authentication_error(opts \\ [])

@spec authentication_error(keyword()) :: t()

Creates an authentication error.

bad_request(opts \\ [])

@spec bad_request(keyword()) :: t()

Creates a bad request error.

bad_symbol(opts \\ [])

@spec bad_symbol(keyword()) :: t()

Creates a bad symbol error.

circuit_open(opts \\ [])

@spec circuit_open(keyword()) :: t()

Creates a circuit breaker open error.

cloudflare_challenge(opts \\ [])

@spec cloudflare_challenge(keyword()) :: t()

Creates a Cloudflare challenge error.

Used when the exchange is reachable but served a Cloudflare anti-bot challenge page (e.g. "Just a moment..."). Inconclusive for integration tests — the client is reaching the right host but needs a browser or approved path to pass the challenge.

exchange_error(message, opts \\ [])

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

Creates a generic exchange error.

Use this for errors that don't fit other categories.

exchange_not_available(opts \\ [])

@spec exchange_not_available(keyword()) :: t()

Creates an exchange not available error.

from_spec_class(class_name)

@spec from_spec_class(String.t()) :: error_type()

Maps a Bourse spec exception class to an error type atom.

Accepts both raw class names and __function: prefixed strings from specs.

Examples

from_spec_class("AuthenticationError")
#=> :authentication_error

from_spec_class("__function:InsufficientFunds")
#=> :insufficient_funds

from_spec_class("UnknownClass")
#=> :exchange_error

from_spec_class(class_name, ancestors)

@spec from_spec_class(String.t(), %{optional(String.t()) => [String.t()]}) ::
  error_type()

Maps a Bourse spec exception class to an error type, walking the upstream class hierarchy when the class is not directly mapped.

ancestors is the per-exchange errors.class_hierarchy.ancestors map (%{class => [ancestor, ...]}, nearest first). When class_name has no direct mapping, the nearest mapped ancestor wins; only when neither the class nor any ancestor is known does it fall back to :exchange_error.

This keeps the client robust to new upstream classes (e.g. AddressPending resolves through InvalidAddress, ChecksumError through InvalidNonce) without enumerating every leaf.

Examples

iex> Bourse.Error.from_spec_class("InsufficientFunds", %{})
:insufficient_funds

iex> ancestors = %{"AddressPending" => ["InvalidAddress", "ExchangeError", "BaseError"]}
iex> Bourse.Error.from_spec_class("AddressPending", ancestors)
:bad_request

iex> Bourse.Error.from_spec_class("TotallyUnknown", %{})
:exchange_error

insufficient_funds(opts \\ [])

@spec insufficient_funds(keyword()) :: t()

Creates an insufficient funds error.

invalid_order(opts \\ [])

@spec invalid_order(keyword()) :: t()

Creates an invalid order error.

invalid_parameters(opts \\ [])

@spec invalid_parameters(keyword()) :: t()

Creates an invalid parameters error.

market_closed(opts \\ [])

@spec market_closed(keyword()) :: t()

Creates a market closed error.

network_error(opts \\ [])

@spec network_error(keyword()) :: t()

Creates a network error.

non_recoverable_types()

@spec non_recoverable_types() :: [error_type()]

Returns all non-recoverable error types.

not_supported(opts \\ [])

@spec not_supported(keyword()) :: t()

Creates a not supported error.

operation_failed(opts \\ [])

@spec operation_failed(keyword()) :: t()

Creates an operation failed error.

order_not_found(opts \\ [])

@spec order_not_found(keyword()) :: t()

Creates an order not found error.

permission_denied(opts \\ [])

@spec permission_denied(keyword()) :: t()

Creates a permission denied error.

rate_limit_exceeded(opts \\ [])

@spec rate_limit_exceeded(keyword()) :: t()

Creates a rate limit exceeded error.

Options

:retry_after - Milliseconds until retry is allowed
:exchange - Exchange ID string
:raw - Original error response from exchange
:hints - List of debugging hint strings

recoverable?(type)

@spec recoverable?(error_type()) :: boolean() | nil

Returns the recoverability classification for an error type.

true — recoverable (can retry automatically)
false — not recoverable (requires intervention)
nil — unknown (generic exchange_error)

recoverable_types()

@spec recoverable_types() :: [error_type()]

Returns all recoverable error types.

retry_class(type)

@spec retry_class(error_type()) :: retry_class()

Returns the canonical retry classification bucket for an error type.

Returns nil for the generic :exchange_error (and any unknown type) — the retry semantics are genuinely unknown for an unmapped error.

Examples

iex> Bourse.Error.retry_class(:rate_limit_exceeded)
:rate_limit

iex> Bourse.Error.retry_class(:authentication_error)
:auth

iex> Bourse.Error.retry_class(:exchange_error)
nil

retry_class_mapping()

@spec retry_class_mapping() :: %{required(error_type()) => retry_class()}

Returns the canonical error_type → retry bucket map.

should_retry?(class)

@spec should_retry?(t() | retry_class()) :: boolean()

Returns whether an error (or retry bucket) is worth retrying.

Retryable buckets are :rate_limit, :network, and :server_busy. An :auth, :non_retryable, or unclassified (nil) error returns false.

Examples

iex> Bourse.Error.should_retry?(:server_busy)
true

iex> Bourse.Error.should_retry?(:auth)
false

iex> Bourse.Error.should_retry?(%Bourse.Error{type: :rate_limit_exceeded, message: "", retry_class: :rate_limit})
true

spec_class_mapping()

@spec spec_class_mapping() :: %{required(String.t()) => error_type()}

Returns the full spec class to error type mapping.