Error codes

Codes are stable and safe to branch on. Messages are descriptive and may change.

Request

invalid_request	400. Malformed JSON or a missing required field.
unsupported_version	400. `messageVersion` outside 2.1.0 and 2.2.0.
amount_out_of_range	422. Above the merchant ceiling or zero.
phone_invalid	422. Not E.164, or absent when the issuer requires SMS.
bin_unmapped	422. BIN outside the mapped range. Session can be retried after mapping, usually within one day.

Authorisation

auth_missing	401. No bearer token.
auth_invalid	401. Revoked, wrong environment, or malformed.
origin_not_allowed	403. Browser call from an origin not registered for the key.
url_not_registered	403. `notificationUrl` or `returnUrl` outside the registered list.

State

not_found	404. Unknown `authenticationId`, or one belonging to another merchant.
idempotency_conflict	409. Same `Idempotency-Key` with a different body.
session_finished	409. The session is terminal; create a new one.
resend_exhausted	409. Three resends already used.
rate_limited	429. Honour `Retry-After`; do not retry in a tight loop.

Handling

Retry only on 429 and 5xx, with exponential backoff and jitter.
Never retry 409 session_finished. Create a new session.
4xx from a user input means the buyer has to fix the data, not you.
Log requestId from every error. Support needs it to trace.

Every error body carries requestId. Quotes without it take longer to resolve.