ExLLM.Infrastructure.Error (ex_llm v0.8.1)

View Source

Standardized error types and utilities for ExLLM.

This module defines consistent error patterns used throughout ExLLM to provide predictable error handling for library consumers.

Error Patterns

All functions should return either {:ok, result} or {:error, reason}.

Error reasons follow these patterns:

Simple Errors (atoms)

  • :not_found - Resource not found
  • :not_connected - Connection not established
  • :invalid_config - Configuration is invalid
  • :not_configured - Required configuration missing
  • :timeout - Operation timed out
  • :unauthorized - Authentication failed

Complex Errors (tuples)

  • {:api_error, details} - API call failed
  • {:validation, field, message} - Validation failed
  • {:connection_failed, reason} - Connection failure
  • {:json_parse_error, reason} - JSON parsing failed

Examples

# Simple error
{:error, :not_found}

# API error with details
{:error, {:api_error, %{status: 404, body: "Not found"}}}

# Validation error
{:error, {:validation, :name, "cannot be empty"}}

# Connection error
{:error, {:connection_failed, :timeout}}

Summary

Functions

Creates a standardized API error.

Creates a standardized authentication error.

Creates a standardized connection failure error.

Checks if a value is an error tuple.

Extracts error reason from error tuple.

Creates a standardized JSON parsing error.

Creates a standardized rate limit error.

Creates a service unavailable error.

Creates a standardized unknown error.

Creates a standardized validation error.

Types

complex_error()

@type complex_error() ::
  {:api_error, map()}
  | {:validation, atom(), String.t()}
  | {:connection_failed, term()}
  | {:json_parse_error, term()}
  | {:invalid_file_type, term()}

error_reason()

@type error_reason() :: simple_error() | complex_error()

result(success_type)

@type result(success_type) :: {:ok, success_type} | {:error, error_reason()}

simple_error()

@type simple_error() ::
  :not_found
  | :not_connected
  | :invalid_config
  | :not_configured
  | :timeout
  | :unauthorized
  | :no_token_usage
  | :server_not_found
  | :unsupported_format

Functions

api_error(status, body)

@spec api_error(integer(), term()) :: {:error, {:api_error, map()}}

Creates a standardized API error.

Parameters

  • status - HTTP status code
  • body - Response body (string or map)

Returns

API error tuple

authentication_error(message)

@spec authentication_error(String.t()) ::
  {:error, {:authentication_error, String.t()}}

Creates a standardized authentication error.

Parameters

  • message - Error message

Returns

Authentication error

connection_error(reason)

@spec connection_error(term()) :: {:error, {:connection_failed, term()}}

Creates a standardized connection failure error.

Parameters

  • reason - Underlying failure reason

Returns

Connection error tuple

error?(arg1)

@spec error?(term()) :: boolean()

Checks if a value is an error tuple.

Parameters

  • value - Value to check

Returns

Boolean indicating if value is an error tuple

get_error_reason(arg1)

@spec get_error_reason({:error, error_reason()} | term()) :: error_reason() | nil

Extracts error reason from error tuple.

Parameters

  • error_tuple - Error tuple

Returns

Error reason or nil if not an error tuple

json_parse_error(reason)

@spec json_parse_error(term()) :: {:error, {:json_parse_error, term()}}

Creates a standardized JSON parsing error.

Parameters

  • reason - JSON parsing failure reason

Returns

JSON parse error tuple

rate_limit_error(message)

@spec rate_limit_error(String.t()) :: {:error, {:rate_limit_error, String.t()}}

Creates a standardized rate limit error.

Parameters

  • message - Error message

Returns

Rate limit error

service_unavailable(message)

@spec service_unavailable(String.t()) :: {:error, {:service_unavailable, String.t()}}

Creates a service unavailable error.

Parameters

  • message - Error message

Returns

Service unavailable error

unknown_error(reason)

@spec unknown_error(term()) :: {:error, {:unknown_error, term()}}

Creates a standardized unknown error.

Parameters

  • reason - Error reason

Returns

Unknown error

validation_error(field, message)

@spec validation_error(atom(), String.t()) ::
  {:error, {:validation, atom(), String.t()}}

Creates a standardized validation error.

Parameters

  • field - Field name (atom)
  • message - Error message (string)

Returns

Validation error tuple