KYCCentral.Error exception (KYC Central v0.9.0)

The single error type returned by every function in this library.

Rather than a tree of exception modules, failures carry a :kind atom, which makes them pleasant to match on:

case KYCCentral.KYC.assess(client, "00445790") do
  {:ok, assessment} -> assessment
  {:error, %KYCCentral.Error{kind: :not_found}} -> :no_such_company
  {:error, %KYCCentral.Error{kind: :rate_limit, retry_after: seconds}} -> {:wait, seconds}
  {:error, error} -> raise error
end

This is also an exception, so raise error works when you would rather not handle a failure locally.

Summary

Types

kind()

What went wrong.

t()

Functions

header(headers, name)

Fetch one header value, case-insensitively.

retry_after(headers)

Read Retry-After out of a response's headers, in seconds.

Types

kind()

@type kind() ::
  :connection
  | :timeout
  | :bad_request
  | :authentication
  | :permission_denied
  | :not_found
  | :unprocessable_entity
  | :rate_limit
  | :server_error
  | :service_unavailable
  | :unexpected_status
  | :job_failed
  | :job_timeout
  | :invalid_argument

What went wrong.

Transport failures:

:connection — the request never produced a response.
:timeout — the request timed out.

API responses:

:bad_request (400) — the request was malformed.
:authentication (401) — no API key was sent, or it is not valid.
:permission_denied (403) — the plan does not include this endpoint; usually an active Professional subscription is required.
:not_found (404) — no such company, officer, charge or filing.
:unprocessable_entity (422) — failed the API's validation rules.
:rate_limit (429) — a rate limit or plan quota was exceeded.
:server_error (5xx) — the API failed to handle a valid request.
:service_unavailable (503) — a dependency the API needs is down.
:unexpected_status — any other non-2xx status.

Queued assessments:

:job_failed — the API reported the queued assessment as failed.
:job_timeout — the assessment did not finish within :poll_timeout.

Caller mistakes, detected before any request is made:

:invalid_argument

t()

@type t() :: %KYCCentral.Error{
  __exception__: true,
  body: term(),
  detail: String.t() | nil,
  headers: map(),
  job_id: String.t() | nil,
  kind: kind(),
  message: String.t(),
  reason: term(),
  retry_after: number() | nil,
  status: pos_integer() | nil
}

Functions

retry_after(headers)

@spec retry_after(map()) :: number() | nil

Read Retry-After out of a response's headers, in seconds.

Returns nil when the header is absent or not a number.