TerminusDB.Error exception (terminusdb_ex v0.1.0)

Copy Markdown View Source

A structured error returned by all terminusdb_ex operations.

Public API functions return {:error, %TerminusDB.Error{}} on failure; the !/1-suffixed variants raise this same struct (it implements the Exception behaviour). The :reason field classifies the failure so callers can pattern match without inspecting HTTP status:

:reasonMeaning
:transportNetwork/transport failure (connection, timeout, …)
:httpNon-2xx response with a non-JSON or unstructured body
:apiTerminusDB API error (structured api:* JSON body)
:decodeResponse body could not be decoded as JSON

Examples

iex> error = TerminusDB.Error.api(400, %{
...>   "@type" => "api:DbCreateErrorResponse",
...>   "api:error" => %{"@type" => "api:DatabaseAlreadyExists"},
...>   "api:message" => "Database already exists.",
...>   "api:status" => "api:failure"
...> })
iex> error.reason
:api
iex> error.api_type
"api:DatabaseAlreadyExists"
iex> Exception.message(error)
"TerminusDB API error 400 (api:DatabaseAlreadyExists): Database already exists."

Summary

Types

reason()
t()

Functions

api(status, body)

Builds an :api error from a TerminusDB structured error body.

decode(exception, body)

Builds a :decode error when the response body cannot be parsed as JSON.

http(status, body)

Builds an :http error from a non-2xx status with an unstructured body.

transport(exception)

Builds a :transport error from an underlying exception (e.g. Req.TransportError).

Types

reason()

@type reason() :: :transport | :http | :api | :decode

t()

@type t() :: %TerminusDB.Error{
  __exception__: term(),
  api_error: map() | nil,
  api_type: String.t() | nil,
  body: term(),
  cause: Exception.t() | nil,
  message: String.t(),
  reason: reason(),
  status: pos_integer() | nil
}

Functions

api(status, body)

@spec api(pos_integer(), map()) :: t()

Builds an :api error from a TerminusDB structured error body.

TerminusDB returns JSON of the shape {"@type": "api:*ErrorResponse", "api:error": {...}, "api:message": "...", "api:status": "api:failure"}. The @type inside api:error (if present) is surfaced as api_type for easy pattern matching, e.g. "api:DatabaseAlreadyExists".

decode(exception, body)

@spec decode(Exception.t(), binary() | nil) :: t()

Builds a :decode error when the response body cannot be parsed as JSON.

http(status, body)

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

Builds an :http error from a non-2xx status with an unstructured body.

transport(exception)

@spec transport(Exception.t()) :: t()

Builds a :transport error from an underlying exception (e.g. Req.TransportError).