CCXT.Error exception (ccxt_client v0.6.1)

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, and whether it's recoverable.

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

Summary

Types

error_type()

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 CCXT spec exception class to an error type atom.

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.

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

t()

@type t() :: %CCXT.Error{
  __exception__: true,
  code: String.t() | integer() | nil,
  exchange: String.t() | nil,
  hints: [String.t()],
  http_status: non_neg_integer() | nil,
  message: String.t(),
  raw: map() | nil,
  recoverable: boolean() | nil,
  retry_after: non_neg_integer() | nil,
  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 CCXT 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

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.

spec_class_mapping()

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

Returns the full spec class to error type mapping.