Vaultx.Base.Error exception (Vaultx v0.7.0)

Comprehensive error handling for Vaultx HashiCorp Vault client.

This module provides a unified error type and utilities for consistent, safe error handling throughout the Vaultx library. All errors are structured, recoverable, and provide both technical and user-friendly information.

Design Principles

Consistency: All errors use the same %Vaultx.Base.Error{} structure
Safety: User-friendly messages that don't leak sensitive information
Recoverability: Clear indication of whether operations should be retried
Context: Rich error context for debugging and monitoring
Standards: HTTP status codes and Vault error conventions

Error Categories

:authentication_failed - Authentication with Vault failed
:authorization_denied - Access denied for the requested operation
:not_found - Requested resource was not found
:invalid_request - Request was malformed or invalid
:server_error - Vault server encountered an error
:network_error - Network connectivity issues
:timeout - Request timed out
:configuration_error - Invalid configuration
:json_decode_error - Failed to parse JSON response
:json_encode_error - Failed to encode JSON request
:ssl_error - SSL/TLS related errors
:rate_limited - Request was rate limited
:connection_error - Connection-related errors
:permission_denied - Permission denied for the operation
:not_implemented - Feature not yet implemented
:http_error - HTTP protocol errors
:unknown_error - Unexpected error occurred

Examples

# Create a new error
error = Vaultx.Base.Error.new(:not_found, "Secret not found at path")

# Create from HTTP response
error = Vaultx.Base.Error.from_http_response(404, %{"errors" => ["path not found"]})

# Create from exception
error = Vaultx.Base.Error.from_exception(%Jason.DecodeError{})

# Check if error is recoverable
if Vaultx.Base.Error.recoverable?(error) do
  # Retry the operation
end

# Get user-friendly message
message = Vaultx.Base.Error.user_message(error)

Summary

Types

error_type()

t()

Functions

debug_info(error)

Returns detailed error information for debugging.

from_exception(exception, opts \\ [])

Creates an error from an exception.

from_http_response(status, body, opts \\ [])

Creates an error from an HTTP response.

new(type, message, opts \\ [])

Creates a new error with the specified type and message.

recoverable?(type)

Checks if an error is recoverable (can be retried).

user_message(error)

Returns a user-friendly error message.

Types

error_type()

@type error_type() ::
  :authentication_failed
  | :authorization_denied
  | :not_found
  | :invalid_request
  | :server_error
  | :network_error
  | :timeout
  | :configuration_error
  | :json_decode_error
  | :json_encode_error
  | :ssl_error
  | :rate_limited
  | :connection_error
  | :permission_denied
  | :not_implemented
  | :http_error
  | :unknown_error

t()

@type t() :: %Vaultx.Base.Error{
  __exception__: true,
  details: map(),
  http_status: integer() | nil,
  message: String.t(),
  recoverable: boolean(),
  request_id: String.t() | nil,
  retry_after: integer() | nil,
  type: error_type(),
  vault_errors: [String.t()]
}

Functions

debug_info(error)

@spec debug_info(t()) :: map()

Returns detailed error information for debugging.

Examples

iex> error = Vaultx.Base.Error.new(:not_found, "Secret not found")
iex> info = Vaultx.Base.Error.debug_info(error)
iex> info.type
:not_found

from_exception(exception, opts \\ [])

@spec from_exception(
  Exception.t(),
  keyword()
) :: t()

Creates an error from an exception.

Examples

iex> error = Vaultx.Base.Error.from_exception(%Jason.DecodeError{})
iex> error.type
:json_decode_error

from_http_response(status, body, opts \\ [])

@spec from_http_response(integer(), map(), keyword()) :: t()

Creates an error from an HTTP response.

Examples

iex> error = Vaultx.Base.Error.from_http_response(404, %{"errors" => ["not found"]})
iex> error.type
:not_found

new(type, message, opts \\ [])

@spec new(error_type(), String.t(), keyword()) :: t()

Creates a new error with the specified type and message.

Examples

iex> error = Vaultx.Base.Error.new(:not_found, "Secret not found")
iex> error.type
:not_found

recoverable?(type)

@spec recoverable?(t() | error_type()) :: boolean()

Checks if an error is recoverable (can be retried).

Examples

iex> error = Vaultx.Base.Error.new(:timeout, "Request timed out")
iex> Vaultx.Base.Error.recoverable?(error)
true

iex> error = Vaultx.Base.Error.new(:authentication_failed, "Invalid token")
iex> Vaultx.Base.Error.recoverable?(error)
false

user_message(error)

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

Returns a user-friendly error message.

Examples

iex> error = Vaultx.Base.Error.new(:not_found, "Secret not found at path")
iex> Vaultx.Base.Error.user_message(error)
"The requested resource was not found"