Codex.Error exception (Codex SDK v0.7.2)

@type kind() ::
  :rate_limit
  | :sandbox_assessment_failed
  | :unknown
  | :realtime_connection_failed
  | :realtime_connection_closed
  | :realtime_session_error
  | :realtime_audio_error
  | :realtime_tool_error
  | :realtime_handoff_error
  | :realtime_guardrail_tripped
  | :voice_stt_error
  | :voice_stt_connection_error
  | :voice_tts_error
  | :voice_workflow_error
  | :voice_pipeline_error
  | :unsupported_feature

t()

@type t() :: %Codex.Error{
  __exception__: true,
  details: map(),
  kind: kind(),
  message: String.t(),
  retry_after_ms: non_neg_integer() | nil
}

Functions

new(kind, message, details \\ %{})

@spec new(atom(), String.t(), map()) :: t()

normalize(error)

@spec normalize(term()) :: t()

Normalizes raw error payloads into %Codex.Error{} structs.

Accepts maps emitted by codex-rs (turn.failed), basic strings, or already constructed %Codex.Error{} structs. Known codes and types are classified into stable :kind atoms so callers can branch on error domains (e.g., rate limits, sandbox assessment failures).

rate_limit(message, opts \\ [])

@spec rate_limit(
  String.t(),
  keyword()
) :: t()

Creates a rate limit error with optional retry-after hint.

Options

:retry_after_ms - Suggested delay before retry in milliseconds
:details - Additional error details map

Examples

iex> error = Codex.Error.rate_limit("Rate limit exceeded", retry_after_ms: 30_000)
iex> error.kind
:rate_limit
iex> error.retry_after_ms
30_000

rate_limit?(arg1)

@spec rate_limit?(t() | term()) :: boolean()

Checks if error is a rate limit error.

Examples

iex> error = Codex.Error.rate_limit("Rate limited")
iex> Codex.Error.rate_limit?(error)
true
iex> Codex.Error.rate_limit?(%Codex.Error{kind: :unknown, message: "Other"})
false

realtime_audio_error(opts \\ [])

@spec realtime_audio_error(keyword()) :: t()

Creates a realtime audio error.

realtime_connection_closed(opts \\ [])

@spec realtime_connection_closed(keyword()) :: t()

Creates a realtime connection closed error.

realtime_connection_failed(opts \\ [])

@spec realtime_connection_failed(keyword()) :: t()

Creates a realtime connection failed error.

realtime_guardrail_tripped(opts \\ [])

@spec realtime_guardrail_tripped(keyword()) :: t()

Creates a realtime guardrail tripped error.

realtime_handoff_error(opts \\ [])

@spec realtime_handoff_error(keyword()) :: t()

Creates a realtime handoff error.

realtime_session_error(opts \\ [])

@spec realtime_session_error(keyword()) :: t()

Creates a realtime session error.

realtime_tool_error(opts \\ [])

@spec realtime_tool_error(keyword()) :: t()

Creates a realtime tool error.

retry_after_ms(arg1)

@spec retry_after_ms(t()) :: non_neg_integer() | nil

Extracts retry-after hint from error if present.

Returns the delay in milliseconds, or nil if not available.

Examples

iex> error = Codex.Error.rate_limit("Rate limited", retry_after_ms: 60_000)
iex> Codex.Error.retry_after_ms(error)
60_000
iex> Codex.Error.retry_after_ms(%Codex.Error{kind: :unknown, message: "Other"})
nil

voice_pipeline_error(opts \\ [])

@spec voice_pipeline_error(keyword()) :: t()

Creates a voice pipeline error.

voice_stt_connection_error(opts \\ [])

@spec voice_stt_connection_error(keyword()) :: t()

Creates a voice STT connection error.

voice_stt_error(opts \\ [])

@spec voice_stt_error(keyword()) :: t()

Creates a voice STT (speech-to-text) error.

voice_tts_error(opts \\ [])

@spec voice_tts_error(keyword()) :: t()

Creates a voice TTS (text-to-speech) error.

voice_workflow_error(opts \\ [])

@spec voice_workflow_error(keyword()) :: t()

Creates a voice workflow error.