Error Decoding

Error Decoding

When a record contains a provider error, decline or response code, the adapter looks it up in a catalog built from the provider's official documentation. Each catalog entry has a link to the page it came from.

What a decoded error contains

Field	Meaning
code	the provider's own code, unchanged
explanation	a short paraphrase of the documented meaning
category	a common category (table below)
retry guidance	what to do about retries (table below)
next step	a concrete action for the developer or the customer
confidence	how sure the decoding is (table below)
documentation	link to the provider's page
outcome known	whether the original operation's result is known

Categories

Category	Typical cause
card_declined	issuer or scheme declined
insufficient_funds	not enough funds or credit
authentication_required	3D Secure or another customer step is needed
authentication_failed	the customer failed or abandoned authentication
invalid_request	missing or malformed parameters
invalid_amount	amount or currency not allowed
payment_method_unavailable	method not enabled, not supported or unavailable
fraud_or_risk	blocked by risk rules or suspected fraud
rate_limiting	too many requests
provider_unavailable	provider or acquirer error or outage
network_or_timeout	timeout or connection problem
duplicate_request	the same request or reference was already used
configuration	account, credentials or settings problem
unknown	not documented, or several documented meanings disagree

Retry guidance

Value	Meaning
do_not_retry	retrying the same request will fail again or is forbidden by the provider or issuer
customer_action_required	the customer has to do something first (authenticate, use another card, add funds)
retry_conditionally	retry only after checking the original outcome or fixing a condition
safe_to_retry_technical_request	a technical retry of the same request is safe
manual_review	a person should look at it
unknown	not enough information

A retry is never shown as safe when the outcome of the original operation is unknown (for example after a timeout). In that case the guidance is retry_conditionally with an instruction to check the payment status first, even if the provider's own text simply says "try again". Recurring advice codes from card schemes, when present, take precedence over a generic decline.

Confidence

Level	Meaning
confirmed	stated directly by the data (used mostly for findings)
strong	exact documented code meaning
possible	fallback, range match, or a code with more than one documented meaning
insufficient	unknown code; the explanation says so instead of guessing

When a code has several documented meanings (for example the same number in two tables), every meaning is shown and confidence is lowered. Unknown codes are reported as unknown.

Where catalogs come from

Catalogs are data files in each adapter (packages/adapters/<id>/src/catalog.ts). The research behind them, with every source URL, is in docs/providers/research/ and docs/providers/high-risk/research/.