LatticeStripe.Error exception (LatticeStripe v0.2.0)

Copy Markdown View Source

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

Summary

Types

error_type()

Stripe error type atom.

t()

A structured Stripe API error.

Functions

from_response(status, decoded_body, request_id)

Build an Error struct from a Stripe API response.

Types

error_type()

@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 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()

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

Functions

from_response(status, decoded_body, request_id)

@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