# `AgentSessionManager.Core.Error`
[🔗](https://github.com/nshkrdotcom/agent_session_manager/blob/v0.8.0/lib/agent_session_manager/core/error.ex#L1)

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"

# `error_category`

```elixir
@type error_category() ::
  :validation
  | :state
  | :resource
  | :provider
  | :storage
  | :runtime
  | :concurrency
  | :tool
  | :unknown
```

# `error_code`

```elixir
@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
  | :stream_closed
  | :context_mismatch
  | :invalid_cursor
  | :session_mismatch
  | :run_mismatch
  | :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
  | :dependency_not_available
  | :migration_required
  | :storage_write_failed
  | :storage_read_failed
  | :timeout
  | :cancelled
  | :policy_violation
  | :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
```

# `t`

```elixir
@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()
}
```

# `all_codes`

```elixir
@spec all_codes() :: [error_code()]
```

Returns all valid error codes.

# `category`

```elixir
@spec category(error_code() | atom()) :: error_category()
```

Returns the category of an error code.

# `concurrency_codes`

```elixir
@spec concurrency_codes() :: [error_code()]
```

Returns concurrency error codes.

# `from_map`

```elixir
@spec from_map(map()) :: {:ok, t()} | {:error, t()}
```

Reconstructs an Error from a map.

# `new`

```elixir
@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", ...}

# `new`

```elixir
@spec new(error_code(), String.t()) :: t()
```

# `new`

```elixir
@spec new(error_code(), String.t(), keyword()) :: t()
```

# `provider_codes`

```elixir
@spec provider_codes() :: [error_code()]
```

Returns provider error codes.

# `resource_codes`

```elixir
@spec resource_codes() :: [error_code()]
```

Returns resource error codes.

# `retryable?`

```elixir
@spec retryable?(error_code() | t()) :: boolean()
```

Checks if an error is retryable.

Accepts either an error code atom or an Error struct.

# `runtime_codes`

```elixir
@spec runtime_codes() :: [error_code()]
```

Returns runtime error codes.

# `storage_codes`

```elixir
@spec storage_codes() :: [error_code()]
```

Returns storage error codes.

# `to_map`

```elixir
@spec to_map(t()) :: map()
```

Converts an Error to a map suitable for JSON serialization.

# `tool_codes`

```elixir
@spec tool_codes() :: [error_code()]
```

Returns tool error codes.

# `valid_code?`

```elixir
@spec valid_code?(atom()) :: boolean()
```

Checks if the given error code is valid.

# `validation_codes`

```elixir
@spec validation_codes() :: [error_code()]
```

Returns validation error codes.

# `wrap`

```elixir
@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, ...}

---

*Consult [api-reference.md](api-reference.md) for complete listing*