Turso.Error exception (turso v0.1.1)

Error handling and representation for Turso API errors.

This module provides a consistent error structure for all Turso API errors, making it easier to handle different error scenarios in your application.

Error Types

The :type field categorizes errors for easier pattern matching:

:unauthorized - Invalid or missing API token (401)
:forbidden - Insufficient permissions (403)
:not_found - Resource not found (404)
:conflict - Resource already exists (409)
:rate_limited - Too many requests (429)
:invalid_request - Bad request parameters (400)
:unprocessable_entity - Request validation failed (422)
:server_error - Internal server error (500+)
:network_error - Connection or network failure
:timeout - Request timeout
:unknown - Unrecognized error

Usage

case Turso.create_database(client, "my-db") do
  {:ok, database} ->
    # Success

  {:error, %Turso.Error{type: :conflict}} ->
    # Database already exists

  {:error, %Turso.Error{type: :rate_limited} = error} ->
    # Rate limited, check error.details for retry info

  {:error, %Turso.Error{} = error} ->
    # Handle other errors
    Logger.error("Turso error: #{error.message}")
end

Summary

Types

error_type()

t()

Functions

auth_error?(arg1)

Checks if the error is an authentication/authorization error.

client_error?(arg1)

Checks if the error is a client error (4xx status codes).

new(response, request_info \\ %{})

Creates a new error from an HTTP response and request information.

parse(response_body, status \\ nil)

Parses an error response body and status code into an Error struct.

rate_limited?(arg1)

Checks if the error is a rate limiting error.

retry_after(arg1)

Extracts retry-after information from rate limiting errors.

retryable?(arg1)

Checks if the error might be resolved by retrying.

server_error?(arg1)

Checks if the error is a server error (5xx status codes).

Types

error_type()

@type error_type() ::
  :unauthorized
  | :forbidden
  | :not_found
  | :conflict
  | :rate_limited
  | :invalid_request
  | :unprocessable_entity
  | :server_error
  | :network_error
  | :timeout
  | :unknown

t()

@type t() :: %Turso.Error{
  __exception__: true,
  details: map() | nil,
  message: String.t(),
  request_method: atom() | nil,
  request_url: String.t() | nil,
  status: integer() | nil,
  type: error_type()
}

Functions

auth_error?(arg1)

@spec auth_error?(t() | any()) :: boolean()

Checks if the error is an authentication/authorization error.

Examples

if Turso.Error.auth_error?(error) do
  # Refresh token or re-authenticate
end

client_error?(arg1)

@spec client_error?(t() | any()) :: boolean()

Checks if the error is a client error (4xx status codes).

Examples

if Turso.Error.client_error?(error) do
  # Don't retry, fix the request
end

new(response, request_info \\ %{})

@spec new(any(), map()) :: t()

Creates a new error from an HTTP response and request information.

Parameters

response - The response tuple or error data
request_info - Optional map with request details (:method, :url)

Examples

Turso.Error.new({:error, %{"status" => 404, "error" => %{"message" => "Not found"}}})

Turso.Error.new(
  {:error, %{"status" => 401}},
  %{method: :post, url: "/organizations/my-org/databases"}
)

parse(response_body, status \\ nil)

@spec parse(any(), integer() | nil) :: t()

Parses an error response body and status code into an Error struct.

Examples

Turso.Error.parse(%{"error" => "Database not found"}, 404)

rate_limited?(arg1)

@spec rate_limited?(t() | any()) :: boolean()

Checks if the error is a rate limiting error.

Examples

if Turso.Error.rate_limited?(error) do
  # Wait before retrying
end

retry_after(arg1)

@spec retry_after(t()) :: integer() | nil

Extracts retry-after information from rate limiting errors.

Returns the number of seconds to wait before retrying, or nil if not available.

Examples

case Turso.Error.retry_after(error) do
  nil -> # No retry info
  seconds -> Process.sleep(seconds * 1000)
end

retryable?(arg1)

@spec retryable?(t() | any()) :: boolean()

Checks if the error might be resolved by retrying.

Rate limited, timeout, and server errors are typically retryable.

Examples

if Turso.Error.retryable?(error) do
  # Wait and retry
end

server_error?(arg1)

@spec server_error?(t() | any()) :: boolean()

Checks if the error is a server error (5xx status codes).

Examples

if Turso.Error.server_error?(error) do
  # Might be temporary, consider retrying
end