Errors and telemetry

v0.0.1

Every Mishka Pay call answers {:ok, struct} or {:error, error}, and every call, request, webhook and inbox job emits telemetry. This page lists the error classes and codes with what to do about each, and every telemetry event with its metadata. Both are the same on every site of a Mishka CMS install. It describes version 0.0.1.

Error classes

The error is a MishkaPay.Errors (Splode) exception. Match on its struct. Show people Exception.message(error), or MishkaPay.Ash.message(error) with the Ash layer. These are plain sentences that never repeat a provider's own words, which can name keys and ids. Never show inspect(error).

ErrorMeansDo
MishkaPay.Errors.InvalidBad input. errors has each field.Show it on the field.
MishkaPay.Errors.DeclinedThe card or buyer was declined. reason says why.Ask for another way to pay.
MishkaPay.Errors.RejectedThe provider refused the request. status, code and param say how.Log it. It is often keys or ids.
MishkaPay.Errors.RefusedYour own checkout gate said no.Show its reason.
MishkaPay.Errors.UnsupportedThe provider cannot do it. operation says what.Pick another provider or path.
MishkaPay.Errors.MissingCredentialsNo keys for that provider and site.The site adds keys.
MishkaPay.Errors.UnknownProviderNo such provider is installed.Supervise it.
MishkaPay.Errors.UnreachableNo answer from the provider.Try later. Nothing was charged twice.

MishkaPay.Errors.BadSignature is the error for a webhook whose signature does not match. The endpoint answers 400 for it.

A request the provider limited (HTTP 429) is a Rejected whose message says to try again in a moment. Its rate_limit_reason says why when the provider told (Stripe: "global-rate", "endpoint-concurrency" and others). Mishka Pay has already retried it, a write only with its idempotency key, and follows the provider's own word on whether a retry is safe.

Rejected and Declined keep the provider's id of the failed request as request_id (Stripe's req_..., PayPal's debug id) and its page about the error as doc_url. Log them and quote the id to the provider's support. Never show them to a buyer. Behind an Ash action, MishkaPay.Ash.provider_error(error) finds the provider's error inside the Ash error.

elixir
with {:error, error} <- MishkaPay.refund(attrs) do
  Logger.warning("refund failed",
    request_id: Map.get(error, :request_id)
  )

  {:error, MishkaPay.Ash.message(error)}
end

Codes Mishka Pay names

These are Rejected codes that Mishka Pay names itself, and what produces them. Other codes are the provider's own, such as Stripe's "insufficient_capabilities_for_transfer" when a seller cannot take transfers yet. param is the refused field, by Mishka Pay's name when it has one, such as "trial_days".

CodeWhen
"idempotency_error"A reference was reused within 24 hours with other details.
"already_exists"The object already exists at the provider.
"resource_missing"The provider has no such object.
"customer_deleted"A customer the provider deleted was read.
"managed_payments_invoice", "managed_payments_shipping"An option Managed Payments does not take, such as an invoice or shipping.
"capture_invoice"capture: :manual on a Stripe account whose default is Managed Payments. Send merchant_of_record: false.
"intent_of_invoice", "intent_of_checkout"An intent that an invoice or a checkout made cannot be canceled. Void the invoice or expire the checkout.
"tax_not_set_up", "tax_location_invalid", "failed_tax_calculation"Stripe Tax is off, Stripe cannot place the address, or Stripe could not count the tax.
"connect_not_set_up", "connect_v1_refused", "connect_needs_sandbox"The platform has not signed up for Connect, Stripe refuses v1 accounts for it, or the flow needs a Stripe sandbox.
"dispute_evidence_page_limit_exceeded"Dispute evidence is longer than the card network allows. Shorten the text or send fewer pages.

A refused input is Errors.Invalid before any request. Examples: a wrong id prefix (pi_ payments, cs_ checkouts, sub_ subscriptions, cus_ customers, txr_ tax rates, mtr_ meters and so on), a float amount, an amount with more decimals than the currency has, an ISK, UGX or MGA amount that is not whole, and metadata over 48 keys of 40 characters with values of 500.

Telemetry events

Every event carries :provider. None carries a key or a buyer's details. Attach with :telemetry.attach_many/4.

EventWhenMetadata
[:mishka_pay, operation, :start | :stop]Each call of MishkaPay. The operation is :checkout, :payment, :refund, :subscription_change, :dispute and so on.:provider, :tenant. On :stop, :outcome (:ok or the error's class).
[:mishka_pay, :credentials, :start | :stop]Each keys lookup.:provider, :tenant. On :stop, :outcome: :ok, :invalid, or why there are no keys (:no_answer, :cannot_run, :raised, :exited, :timeout).
[:mishka_pay, :request, :start | :stop | :exception]Each HTTP request to a provider.:provider, :method, :path, :idempotency_key. :status on :stop.
[:mishka_pay, :request, :retry]Before each retry.:wait in milliseconds, :attempt, the :status or network :reason, :retry_after, :rate_limit_reason.
[:mishka_pay, :inbox, :process, :start | :stop]Each try of the Ash inbox at one event.:provider, :tenant, :type, :event_id. On :stop, :outcome (:processed or :retry) and the measurement :lag in milliseconds since it was stored.
[:mishka_pay, :inbox, :failed]An inbox event ran out of tries.:provider, :tenant, :type, :event_id.
[:mishka_pay, :webhook, :start | :stop]Each webhook.:provider. On :stop, the :status, the :outcome (ok, mismatch, too_old, missing_credentials, too_large and others), and for a checked event its :tenant, :type and :id. A tenant appears only once the signature proves it.