Candil.Error exception (Candil v3.0.0)

@type reason() ::
  :model_not_found
  | :engine_not_running
  | :http_error
  | :server_error
  | :auth_error
  | :timeout
  | :rate_limited
  | :invalid_api_key
  | :context_overflow
  | :provider_not_found
  | :invalid_request
  | :engine_exited
  | :startup_timeout
  | :circuit_open
  | :execution_failed
  | :backend_unavailable
  | :cancelled

t()

@type t() :: %Candil.Error{__exception__: true, context: map(), reason: reason()}

Functions

auth_error(status, body \\ nil)

@spec auth_error(pos_integer(), term()) :: t()

Create an auth error (401/403).

backend_unavailable(reason)

@spec backend_unavailable(atom() | term()) :: t()

Create a backend-unavailable error (the Backend behaviour module is not loaded, or its implementation raised at startup).

cancelled(ref \\ nil)

@spec cancelled(term()) :: t()

Create a cancellation error (caller cancelled via Candil.Llm.cancel/1).

context_overflow(token_count, max_tokens)

@spec context_overflow(non_neg_integer(), non_neg_integer()) :: t()

Creates a context overflow error when messages exceed the model's context window.

engine_exited(code, model_alias)

@spec engine_exited(non_neg_integer(), atom()) :: t()

Creates an engine exited error with exit code.

engine_not_running(engine_alias)

@spec engine_not_running(Candil.Engine.alias() | term()) :: t()

Creates an error for an engine that is not running.

from_http_status(status, body)

@spec from_http_status(non_neg_integer(), term()) :: t()

Build a typed error directly from an HTTP status code and body. See http_error/2.

http_error(status, body \\ nil)

@spec http_error(pos_integer(), term()) :: t()

Creates an HTTP error with status and optional body.

If status matches a known category (401/403 → :auth_error, 429 → :rate_limited, 5xx → :server_error, 404 with a model reference → :model_not_found), the reason is normalized to the specific kind. Otherwise it stays :http_error.

invalid_api_key()

@spec invalid_api_key() :: t()

Creates an invalid API key error.

invalid_request(message)

@spec invalid_request(binary()) :: t()

Creates an invalid request error with a message.

kind(error)

@spec kind(t()) :: reason()

Returns the error kind (alias for reason/0).

Provided so callers can write error.kind instead of error.reason if they prefer. The struct field is still named :reason for source-compatibility with existing call-sites.

model_not_found(model_alias)

@spec model_not_found(Candil.Model.alias() | term()) :: t()

Creates an error for a model that was not found.

provider_not_found(provider_alias)

@spec provider_not_found(Candil.Provider.alias() | term()) :: t()

Creates a provider not found error.

rate_limited(retry_after \\ nil)

@spec rate_limited(term()) :: t()

Creates a rate limiting error.

server_error(status, body \\ nil)

@spec server_error(pos_integer(), term()) :: t()

Create a server error (5xx).

startup_timeout(model_alias)

@spec startup_timeout(atom()) :: t()

Creates a startup timeout error.

timeout(context \\ %{})

@spec timeout(term()) :: t()

Creates a timeout error.

wrap(reason)

@spec wrap(term()) :: t()

Wraps a raw error reason into a Candil.Error.