# `LatticeStripe.Error`
[🔗](https://github.com/szTheory/lattice_stripe/blob/v0.2.0/lib/lattice_stripe/error.ex#L1)

Structured error type for Stripe API errors.

All errors returned by `LatticeStripe.Client.request/2` are wrapped in this struct.
The `:type` field is always an atom, enabling clean pattern matching:

    case LatticeStripe.Customer.create(client, params) do
      {:ok, customer} -> handle_success(customer)
      {:error, %LatticeStripe.Error{type: :card_error, code: code}} -> handle_card_error(code)
      {:error, %LatticeStripe.Error{type: :authentication_error}} -> handle_auth_error()
      {:error, %LatticeStripe.Error{type: :rate_limit_error}} -> handle_rate_limit()
      {:error, %LatticeStripe.Error{}} -> handle_generic_error()
    end

## Fields

- `type` - Error category atom: `:card_error | :invalid_request_error | :authentication_error | :rate_limit_error | :api_error | :idempotency_error | :connection_error`
- `code` - Stripe error code string (e.g., `"card_declined"`, `"missing_param"`) or `nil`
- `message` - Human-readable error message
- `status` - HTTP status integer, or `nil` for connection errors (no HTTP response received)
- `request_id` - Stripe request ID from `Request-Id` response header, or `nil`
- `param` - Parameter name that caused the error (e.g., `"card[number]"`), or `nil`
- `decline_code` - Decline code for card errors (e.g., `"insufficient_funds"`), or `nil`
- `charge` - Stripe charge ID associated with the error, or `nil`
- `doc_url` - URL to Stripe documentation for this error, or `nil`
- `raw_body` - Full decoded error body map — escape hatch for fields not yet in the struct, or `nil`

# `error_type`

```elixir
@type error_type() ::
  :card_error
  | :invalid_request_error
  | :authentication_error
  | :rate_limit_error
  | :api_error
  | :idempotency_error
  | :connection_error
```

Stripe error type atom.

See the [Stripe error types documentation](https://docs.stripe.com/api/errors) for details.

- `:card_error` — The card was declined or has an issue (e.g., `"card_declined"`, `"expired_card"`)
- `:invalid_request_error` — Invalid parameters in the request (e.g., missing required field)
- `:authentication_error` — Invalid or missing API key
- `:rate_limit_error` — Too many requests in too short a time
- `:api_error` — Stripe server error or unexpected response
- `:idempotency_error` — The same idempotency key was reused with different parameters
- `:connection_error` — Network-level failure, no HTTP response received

# `t`

```elixir
@type t() :: %LatticeStripe.Error{
  __exception__: true,
  charge: String.t() | nil,
  code: String.t() | nil,
  decline_code: String.t() | nil,
  doc_url: String.t() | nil,
  message: String.t() | nil,
  param: String.t() | nil,
  raw_body: map() | nil,
  request_id: String.t() | nil,
  status: pos_integer() | nil,
  type: error_type()
}
```

A structured Stripe API error.

All errors from `LatticeStripe.Client.request/2` are wrapped in this struct.
Pattern match on `type` to handle specific error categories.

See the [Stripe error object](https://docs.stripe.com/api/errors) for field definitions.

- `type` - Error category atom (always present)
- `code` - Stripe error code string (e.g., `"card_declined"`, `"missing_param"`), or `nil`
- `message` - Human-readable error description
- `status` - HTTP status integer, or `nil` for `:connection_error`
- `request_id` - Stripe `Request-Id` header value for support, or `nil`
- `param` - Parameter name that caused the error (e.g., `"card[number]"`), or `nil`
- `decline_code` - Card decline reason (e.g., `"insufficient_funds"`), or `nil`
- `charge` - Stripe charge ID associated with the error, or `nil`
- `doc_url` - Stripe documentation URL for this specific error, or `nil`
- `raw_body` - Full decoded error body — escape hatch for fields not in the struct, or `nil`

# `from_response`

```elixir
@spec from_response(pos_integer(), map(), String.t() | nil) :: t()
```

Build an `Error` struct from a Stripe API response.

Called by `Client.request/2` when the HTTP status indicates an error (4xx or 5xx).

## Parameters

- `status` - HTTP status code integer
- `decoded_body` - Decoded JSON body map
- `request_id` - Value of the `Request-Id` response header, or `nil`

---

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