Error catalogue

Every error carries a stable code alongside the human message. Successful responses carry no code.

Branch on code, never on message. code does not change with Accept-Language; every message except the routing 404 does.

A 422 message holds the first error, suffixed with (and N more errors) when there are several; errors groups them by field.

Trap on a multi-error 422: code names only one of the failing fields, and not necessarily the one quoted in message. POST /payments with an empty body answers message about amount and code: "external_reference_required", with all three fields in errors. Use code for single-field failures and for the 401/404/405 families; on a multi-field 422, walk the keys of errors, which are stable and complete.

Changed 2026-08-21. Earlier versions of this guide stated that this API had no machine-readable error codes, and the sample clients here classified errors by matching message text as a result. Codes exist now, on every error, and the samples have been updated to use them. If you copied an older sample, that is the line to change: text matching is no longer merely fragile - for the numeric-id mistake it is actively wrong (12.3).

15.0 When a card is declined: which code to read, and what to retry

A declined charge comes back as card_declined at the Connect level. That tells you nothing about why, and the why is what decides your next move. The reason is in IsoResponseCode (and sometimes in Errors), and that is the field to branch on.

Connect does not retry a declined payment for you, and there is no retryable flag. Deciding whether to invite the customer to try again is your checkout's job. Do not confuse this with the webhook retries in §14: those redeliver a notification, they never re-attempt a charge.

The four groups that matter in practice:

That last row is the one to get right. Those are not "try again later" - they are the issuer saying something is wrong with the card itself, and repeating the attempt is a signal on the merchant's account, not a chance at a sale.

The common codes, after a charge attempt:

This is the ISO 8583 set. The processor publishes more, less common ones (06–11, 15–29, 31–32, 35–40, 52–53, 60, 62–68, 75–90, 92–95, N0, N3, N4, various P codes, XA / XD). Treat an unrecognised code as "do not retry" and log it, rather than guessing which group it belongs to.

Codes from the 3-D Secure step, which happen before or around the charge and are not approvals:

Source: the API team, 2026-08-25, relaying the processor's reference. §16.2 lists the sandbox cards that produce several of these on demand.

15.1 Common 422 messages