Normalized error taxonomy for Agent Session Manager.
Provides machine-readable error codes organized into categories, with support for provider-specific error details and context.
Error Categories
- Validation: Input and format validation errors
- Resource: Not found, already exists, duplicates
- Provider: External AI provider errors (rate limits, timeouts, auth)
- Storage: Persistence layer errors
- Runtime: Timeouts, cancellations, internal errors
- Tool: Tool execution errors
Usage
# Create a basic error
error = Error.new(:validation_error, "Invalid input provided")
# Create with details and context
error = Error.new(:session_not_found, "Session not found",
details: %{session_id: "session-123"},
context: %{operation: "get"}
)
# Wrap a provider error
error = Error.new(:provider_rate_limited, "Rate limited",
provider_error: %{status_code: 429, body: "Too many requests"}
)
# Check if error is retryable
Error.retryable?(error) # => true
# Raise an error
raise Error, code: :validation_error, message: "Invalid input"Summary
Functions
Returns all valid error codes.
Returns the category of an error code.
Returns concurrency error codes.
Reconstructs an Error from a map.
Creates a new error with the given code and an optional message.
Returns provider error codes.
Returns resource error codes.
Checks if an error is retryable.
Returns runtime error codes.
Returns storage error codes.
Converts an Error to a map suitable for JSON serialization.
Returns tool error codes.
Checks if the given error code is valid.
Returns validation error codes.
Wraps an existing exception into an Error struct.
Types
@type error_category() ::
:validation
| :state
| :resource
| :provider
| :storage
| :runtime
| :concurrency
| :tool
| :unknown
@type error_code() ::
:validation_error
| :invalid_input
| :missing_required_field
| :invalid_format
| :invalid_status
| :invalid_transition
| :invalid_event_type
| :invalid_capability_type
| :missing_required_capability
| :not_found
| :session_not_found
| :run_not_found
| :capability_not_found
| :already_exists
| :duplicate_capability
| :provider_error
| :provider_unavailable
| :provider_rate_limited
| :provider_timeout
| :provider_authentication_failed
| :provider_quota_exceeded
| :storage_error
| :storage_connection_failed
| :storage_write_failed
| :storage_read_failed
| :timeout
| :cancelled
| :internal_error
| :unknown_error
| :tool_error
| :tool_not_found
| :tool_execution_failed
| :tool_permission_denied
| :max_sessions_exceeded
| :max_runs_exceeded
| :capability_not_supported
| :invalid_operation
@type t() :: %AgentSessionManager.Core.Error{ __exception__: true, code: error_code(), context: map(), details: map(), message: String.t(), provider_error: map() | nil, stacktrace: list() | nil, timestamp: DateTime.t() }
Functions
@spec all_codes() :: [error_code()]
Returns all valid error codes.
@spec category(error_code() | atom()) :: error_category()
Returns the category of an error code.
@spec concurrency_codes() :: [error_code()]
Returns concurrency error codes.
Reconstructs an Error from a map.
@spec new(error_code()) :: t()
Creates a new error with the given code and an optional message.
Examples
iex> Error.new(:validation_error, "Invalid input")
%Error{code: :validation_error, message: "Invalid input", ...}
iex> Error.new(:validation_error)
%Error{code: :validation_error, message: "Validation error occurred", ...}@spec new(error_code(), String.t()) :: t()
@spec new(error_code(), String.t(), keyword()) :: t()
@spec provider_codes() :: [error_code()]
Returns provider error codes.
@spec resource_codes() :: [error_code()]
Returns resource error codes.
@spec retryable?(error_code() | t()) :: boolean()
Checks if an error is retryable.
Accepts either an error code atom or an Error struct.
@spec runtime_codes() :: [error_code()]
Returns runtime error codes.
@spec storage_codes() :: [error_code()]
Returns storage error codes.
Converts an Error to a map suitable for JSON serialization.
@spec tool_codes() :: [error_code()]
Returns tool error codes.
Checks if the given error code is valid.
@spec validation_codes() :: [error_code()]
Returns validation error codes.
@spec wrap(error_code(), Exception.t(), keyword()) :: t()
Wraps an existing exception into an Error struct.
Examples
iex> Error.wrap(:internal_error, RuntimeError.exception("Something broke"))
%Error{code: :internal_error, ...}