# `CCXT.Error`
[🔗](https://github.com/ZenHive/ccxt_client/blob/main/lib/ccxt/error.ex#L1)

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

# `error_type`

```elixir
@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`

```elixir
@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()
}
```

# `access_restricted`

```elixir
@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`

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

Creates an authentication error.

# `bad_request`

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

Creates a bad request error.

# `bad_symbol`

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

Creates a bad symbol error.

# `circuit_open`

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

Creates a circuit breaker open error.

# `cloudflare_challenge`

```elixir
@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`

```elixir
@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`

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

Creates an exchange not available error.

# `from_spec_class`

```elixir
@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`

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

Creates an insufficient funds error.

# `invalid_order`

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

Creates an invalid order error.

# `invalid_parameters`

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

Creates an invalid parameters error.

# `market_closed`

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

Creates a market closed error.

# `network_error`

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

Creates a network error.

# `non_recoverable_types`

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

Returns all non-recoverable error types.

# `not_supported`

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

Creates a not supported error.

# `operation_failed`

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

Creates an operation failed error.

# `order_not_found`

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

Creates an order not found error.

# `permission_denied`

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

Creates a permission denied error.

# `rate_limit_exceeded`

```elixir
@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?`

```elixir
@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`

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

Returns all recoverable error types.

# `spec_class_mapping`

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

Returns the full spec class to error type mapping.

---

*Consult [api-reference.md](api-reference.md) for complete listing*