TypeDB.Error exception (TypeDB v0.1.0)

Copy Markdown View Source

The single exception type raised (or returned) by every TypeDB operation.

Errors carry a :kind describing where the failure came from:

  • :server — TypeDB answered with a structured error body. :code holds the TypeDB error code (e.g. "TSV11", "AUT3", "HSR4"), :status the HTTP status, and :message the server's message, including its cause trace.
  • :transport — the request never produced an HTTP response (connection refused, DNS failure, TLS failure, socket closed).
  • :timeout — the request exceeded the configured timeout.
  • :unauthenticated — credentials were rejected, or the token expired and could not be renewed.
  • :decode — the response body was not valid JSON, or did not match the shape this driver expects.
  • :config — the driver was configured incorrectly. Raised at start-up.

Matching on TypeDB error codes

case TypeDB.query(conn, "social", "match $x isa nonexistent;") do
  {:error, %TypeDB.Error{kind: :server, code: code}} -> {:bad_query, code}
  {:ok, answer} -> answer
end

Error codes are stable across TypeDB releases and are the recommended thing to branch on; messages are not.

Summary

Types

kind()
t()

Functions

from_response(status, body)

Builds an error from a TypeDB error response body.

new(kind, message, opts \\ [])

Builds an error.

Types

kind()

@type kind() :: :server | :transport | :timeout | :unauthenticated | :decode | :config

t()

@type t() :: %TypeDB.Error{
  __exception__: term(),
  body: term(),
  code: String.t() | nil,
  kind: kind(),
  message: String.t(),
  reason: term(),
  status: pos_integer() | nil
}

Functions

from_response(status, body)

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

Builds an error from a TypeDB error response body.

TypeDB error bodies are %{"code" => code, "message" => message}. Anything else is reported verbatim so that no information is lost.

new(kind, message, opts \\ [])

@spec new(kind(), String.t(), keyword()) :: t()

Builds an error.

Public because TypeDB.HTTP is a public extension point and TypeDB.HTTP.request/6 is required to return one of these. Application code should be matching on errors, not constructing them.

TypeDB.Error.new(:transport, "connection refused", reason: :econnrefused)

Options

  • :code — TypeDB's own error code, for :server errors
  • :status — the HTTP status
  • :reason — the underlying term, whatever it was
  • :body — the response body that could not be understood