ExDaytona.Error (ex_daytona v0.3.0)

Copy Markdown View Source

Normalized error for the SDK facade.

The generated openapi-generator client returns three different shapes for failures (spec-declared error models as {:ok, error_struct}, undeclared statuses as {:error, %Tesla.Env{}}, and transport failures as {:error, reason}). normalize/1 collapses all of them into {:error, %ExDaytona.Error{}} so facade callers match one shape:

  • status — HTTP status, or nil for transport failures
  • message — human-readable message
  • code — the API's error code string, when it sent one
  • details — the raw error payload (decoded map, model struct, or transport reason) for anything the other fields don't capture

Response metadata (populated when the failing call carried it — facade calls and generated calls made with response: :full):

  • headers — normalized response headers
  • request_id — provider request/correlation id
  • rate_limit%{limit, remaining, reset} when the provider sent it
  • retry_after — parsed Retry-After seconds
  • retry_count — transport retries the SDK performed

Outcome classification

outcome distinguishes what the failure proves:

  • :definite — the provider answered; the request was rejected or completed with a known response
  • :unknown — the transport failed (timeout, connection loss) and a non-idempotent request MAY have been accepted before the failure. For idempotent requests an :unknown outcome is safe to retry; for POSTs the application must reconcile before retrying.

Summary

Functions

Build an ExDaytona.Error from any failure shape the generated client produces.

Collapse a generated-client result into {:ok, value} or {:error, %ExDaytona.Error{}}.

Like normalize/1, but keeps the full %ExDaytona.Response{} envelope on success instead of unwrapping to data.

Types

t()

@type t() :: %ExDaytona.Error{
  code: String.t() | nil,
  details: term(),
  headers: [{binary(), binary()}] | nil,
  message: String.t() | nil,
  outcome: :definite | :unknown,
  rate_limit: ExDaytona.Response.rate_limit() | nil,
  request_id: binary() | nil,
  retry_after: non_neg_integer() | nil,
  retry_count: non_neg_integer() | nil,
  status: non_neg_integer() | nil
}

Functions

from(error)

@spec from(term()) :: t()

Build an ExDaytona.Error from any failure shape the generated client produces.

normalize(arg)

@spec normalize(term()) :: {:ok, term()} | {:error, t()}

Collapse a generated-client result into {:ok, value} or {:error, %ExDaytona.Error{}}.

Success values (decoded models, lists, maps, and 2xx Tesla.Env passthroughs) are left untouched. Results from calls made with response: :full are unwrapped to their data on success and enriched with the response metadata on failure.

normalize_full(result)

@spec normalize_full(term()) :: {:ok, ExDaytona.Response.t()} | {:error, t()}

Like normalize/1, but keeps the full %ExDaytona.Response{} envelope on success instead of unwrapping to data.