Pristine.Error exception (Pristine v0.3.0)

Structured error types for API responses.

This module provides a unified error representation for all types of errors that can occur during API requests, including:

HTTP response errors (4xx, 5xx)
Connection errors
Timeout errors

Error Types

Type	Description
`:bad_request`	400 - Bad request
`:authentication`	401 - Authentication failed
`:permission_denied`	403 - Permission denied
`:not_found`	404 - Resource not found
`:conflict`	409 - Conflict/lock timeout
`:unprocessable_entity`	422 - Validation failed
`:rate_limit`	429 - Too many requests
`:internal_server`	5xx - Server error
`:timeout`	Request timed out
`:connection`	Connection failed
`:unknown`	Unknown error type

Example

case make_request() do
  {:ok, response} ->
    {:ok, response}

  {:error, %Pristine.Error{type: :rate_limit} = error} ->
    Logger.warning("Rate limited: #{Error.message(error)}")
    {:retry, error}

  {:error, %Pristine.Error{type: :authentication}} ->
    {:error, :invalid_credentials}

  {:error, error} ->
    {:error, Error.message(error)}
end

Summary

Types

error_type()

t()

Functions

connection_error(reason)

Create a connection error.

connection_error(reason, opts)

from_response(response)

Create an error from an HTTP response.

from_response(response, opts)

message(exception)

Get a human-readable error message.

retriable?(error)

Determine if an error is retriable.

timeout_error()

Create a timeout error.

validation_error(reason, body, opts \\ [])

Create a validation error.

Types

error_type()

@type error_type() ::
  :bad_request
  | :authentication
  | :permission_denied
  | :not_found
  | :conflict
  | :unprocessable_entity
  | :rate_limit
  | :internal_server
  | :timeout
  | :connection
  | :unknown

t()

@type t() :: %Pristine.Error{
  __exception__: true,
  additional_data: term(),
  body: term(),
  documentation_url: String.t() | nil,
  headers: map(),
  message: String.t() | nil,
  provider: atom() | String.t() | nil,
  provider_code: atom() | nil,
  request_id: String.t() | nil,
  response: Pristine.Core.Response.t() | nil,
  retry_after_ms: non_neg_integer() | nil,
  status: integer() | nil,
  type: error_type()
}

Functions

connection_error(reason)

@spec connection_error(term()) :: t()

Create a connection error.

Examples

iex> error = Error.connection_error(:econnrefused)
iex> error.type
:connection

connection_error(reason, opts)

@spec connection_error(term(), keyword()) :: t()

from_response(response)

@spec from_response(Pristine.Response.t() | Pristine.Core.Response.t()) :: t()

Create an error from an HTTP response.

Maps the HTTP status code to an error type and preserves the response body and headers for inspection.

Examples

iex> response = %Response{status: 429, body: "Too many requests"}
iex> error = Error.from_response(response)
iex> error.type
:rate_limit

from_response(response, opts)

@spec from_response(Pristine.Core.Response.t(), keyword()) :: t()

message(exception)

@spec message(t()) :: String.t()

Get a human-readable error message.

Returns the custom message if set, otherwise returns a default message based on the error type.

This function is also the Exception callback for Exception.message/1.

Examples

iex> Error.message(%Error{message: "Custom message"})
"Custom message"

iex> Error.message(%Error{type: :rate_limit})
"Rate limit exceeded"

retriable?(error)

@spec retriable?(t()) :: boolean()

Determine if an error is retriable.

Checks both the error type and any x-should-retry header in the response (if present).

Retriable Types

:rate_limit - 429 errors (usually with Retry-After)
:internal_server - 5xx errors
:timeout - Request timeouts
:connection - Connection failures

Examples

iex> Error.retriable?(%Error{type: :rate_limit})
true

iex> Error.retriable?(%Error{type: :not_found})
false

timeout_error()

@spec timeout_error() :: t()

Create a timeout error.

Examples

iex> error = Error.timeout_error()
iex> error.type
:timeout

validation_error(reason, body, opts \\ [])

@spec validation_error(term(), term(), keyword()) :: t()

Create a validation error.