Nombaone.
View Source
Errors are a feature.
Every failed call resolves to {:error, error} (or raises, from a !
variant), where error is one of the structs in this family. Each API error
carries everything the wire said: the stable machine code to branch on, a
human hint telling you exactly what to do next, a doc_url deep-linking
into the error reference, per-field details on validation failures, and the
request_id to quote to support.
Branch on the code, or match the struct
The code is stable across API versions — branch on it:
case Nombaone.Subscriptions.create(client, params) do
{:ok, subscription} -> subscription
{:error, %{code: "SUBSCRIPTION_PAYMENT_METHOD_REQUIRED"}} -> attach_a_card()
{:error, error} -> Logger.error(Exception.message(error))
endOr match the struct module, keyed by HTTP status class:
Plus the transport-level Nombaone.ConnectionError / Nombaone.TimeoutError,
and Nombaone.WebhookVerificationError from the webhooks helper.
Every error struct is also an Elixir exception, so Exception.message/1
renders the message with the hint appended, and ! methods can raise it.
Summary
Types
A machine-readable error code. Modeled as a plain string and kept open —
a code the API adds tomorrow still parses today. See public_error_codes/0
for the known set.
Any error this SDK returns or raises.
Functions
The fallback code for an HTTP status when the body carries none (a proxy error page, say). Never crashes the parser.
Build the right error struct from a non-2xx response: the parsed body (a map
or nil for a non-JSON body) and a header lookup map with lowercase keys.
The known set of public error codes, vendored from the platform. The wire may still emit a code outside this list — the SDK passes it through unchanged.
Types
@type code() :: String.t()
A machine-readable error code. Modeled as a plain string and kept open —
a code the API adds tomorrow still parses today. See public_error_codes/0
for the known set.
@type t() :: Nombaone.APIError.t() | Nombaone.BadRequestError.t() | Nombaone.AuthenticationError.t() | Nombaone.PermissionDeniedError.t() | Nombaone.NotFoundError.t() | Nombaone.ConflictError.t() | Nombaone.ValidationError.t() | Nombaone.RateLimitError.t() | Nombaone.ServerError.t() | Nombaone.ConnectionError.t() | Nombaone.TimeoutError.t() | Nombaone.WebhookVerificationError.t()
Any error this SDK returns or raises.
Functions
@spec default_code_for_status(non_neg_integer()) :: String.t()
The fallback code for an HTTP status when the body carries none (a proxy error page, say). Never crashes the parser.
@spec from_response(non_neg_integer(), map() | nil, %{ optional(String.t()) => String.t() }) :: t()
Build the right error struct from a non-2xx response: the parsed body (a map
or nil for a non-JSON body) and a header lookup map with lowercase keys.
@spec public_error_codes() :: [String.t()]
The known set of public error codes, vendored from the platform. The wire may still emit a code outside this list — the SDK passes it through unchanged.