Magpie.Error exception (Magpie v0.8.1)

Copy Markdown View Source

Normalized Dropbox API error.

Every Magpie function returns {:error, %Magpie.Error{}} when Dropbox answers with a non-success status:

  • status — the HTTP status code (e.g. 409)
  • summary — Dropbox's error_summary string when present (e.g. "path/not_found/.."), nil otherwise
  • body — the full decoded error payload
  • request_id — Dropbox's request identifier, useful when contacting support
  • endpoint — normalized API route when the error came through the HTTP layer
  • attempts — number of HTTP attempts, including authentication replay
  • retry_after — server-requested delay in milliseconds, or nil

It is also an exception, so it can be raised — Magpie.Pager streams do exactly that, since a Stream cannot return an error tuple mid-enumeration:

case Magpie.Files.create_folder(client, "/Existing") do
  {:ok, %Magpie.FolderMetadata{} = folder} -> folder
  {:error, %Magpie.Error{status: 409, summary: "path/conflict" <> _}} -> :already_exists
  {:error, error} -> raise error
end

Summary

Functions

Returns whether an error represents failed authentication or authorization.

Returns whether Dropbox reported a path, file, or folder conflict.

Returns a safe diagnostic map without response bodies or credentials.

Returns whether Dropbox refused a write, copy, or move for lack of storage: the user's quota, a team folder's limit, or a member folder's limit.

Returns whether an error represents a content integrity mismatch.

Builds a Magpie.Error from an HTTP status and a decoded response body, extracting Dropbox's error_summary when present.

Returns whether Dropbox reported that the requested resource was not found.

Returns whether Dropbox rate-limited the request.

Returns the required scope reported by Dropbox, or nil.

Returns whether retrying the operation may succeed without changing it.

Returns whether the user has used up their monthly upload traffic, so uploads will keep failing until the allowance resets.

Types

t()

@type t() :: %Magpie.Error{
  __exception__: term(),
  attempts: non_neg_integer(),
  body: term(),
  endpoint: String.t() | nil,
  request_id: String.t() | nil,
  retry_after: non_neg_integer() | nil,
  status: pos_integer(),
  summary: String.t() | nil
}

Functions

auth?(error)

@spec auth?(term()) :: boolean()

Returns whether an error represents failed authentication or authorization.

conflict?(error)

@spec conflict?(term()) :: boolean()

Returns whether Dropbox reported a path, file, or folder conflict.

diagnostics(error)

@spec diagnostics(t()) :: map()

Returns a safe diagnostic map without response bodies or credentials.

:retry_after is milliseconds, :attempts counts HTTP attempts (including an authentication replay), and :endpoint identifies the API route.

insufficient_space?(error)

@spec insufficient_space?(term()) :: boolean()

Returns whether Dropbox refused a write, copy, or move for lack of storage: the user's quota, a team folder's limit, or a member folder's limit.

integrity?(arg1)

@spec integrity?(term()) :: boolean()

Returns whether an error represents a content integrity mismatch.

new(status, body, headers \\ [])

Builds a Magpie.Error from an HTTP status and a decoded response body, extracting Dropbox's error_summary when present.

OAuth 2 errors (Magpie.Auth) have no error_summary — their error field is a plain string such as "invalid_grant", which is used as the summary instead.

iex> Magpie.Error.new(409, %{"error_summary" => "path/conflict/folder/.."}).summary
"path/conflict/folder/.."

iex> Magpie.Error.new(400, %{"error" => "invalid_grant"}).summary
"invalid_grant"

not_found?(error)

@spec not_found?(term()) :: boolean()

Returns whether Dropbox reported that the requested resource was not found.

rate_limited?(arg1)

@spec rate_limited?(term()) :: boolean()

Returns whether Dropbox rate-limited the request.

required_scope(arg1)

@spec required_scope(t()) :: String.t() | nil

Returns the required scope reported by Dropbox, or nil.

retryable?(arg1)

@spec retryable?(term()) :: boolean()

Returns whether retrying the operation may succeed without changing it.

upload_traffic_limit?(error)

@spec upload_traffic_limit?(term()) :: boolean()

Returns whether the user has used up their monthly upload traffic, so uploads will keep failing until the allowance resets.