Error Codes Reference

This page catalogs the result codes the SDK White Label returns. Use it to map a code to its cause and decide how to react. For a task-oriented walkthrough, see Troubleshooting.

Result code scheme

Every outcome carries a result code. The prefix identifies the failure class.

Prefix	Type	Meaning
`00`	SUCCESS	Transaction approved or paid.
`1-`	POS_ERROR	Local, terminal, card-read, or operator error (ADQ family).
`3-`	Cryptographic	Reserved for cryptographic errors. Defined, but not emitted today.
`33-`	HOST_ERROR	Payment service (SEP) error — an HTTP error or a host decline.

Examples

Code	Meaning
`00`	Approved.
`1-02`	Canceled by the user or operator (or a kernel `TIMEOUT` / `CANCELED`).
`1-21`	Offline decline or generic terminal error.
`33-<reason>`	Host decline. `<reason>` is the `reason_code` from the SEP response (HTTP 200, `DENIED`).
`33-<httpCode>`	HTTP error returned by SEP, for example `33-400`, `33-401`, `33-500`.
`33-99`	Generic host error, with no usable code.

Host errors are migrating from the older 4-xx prefix to 33-xx: the digits stay the same (4-503 becomes 33-503). Terminals not yet updated may still return 4-xxx. Treat 4-xxx and 33-xxx as equivalent.

Cause categories

Every non-approval belongs to one category, which tells you how to react. Each host code below lists its category.

Category	Meaning
Cardholder / card	The issuer or card declined the operation. Ask for another card or have the customer contact their bank.
Transient — retry	A temporary condition. Retry after a short wait; check the transaction first if a timeout occurred.
Duplicate / in progress	The transaction may already be complete or canceled. Check before retrying.
Reference not found	The `paymentId` or reference does not match a transaction. Confirm it and the environment.
Merchant / product config	The merchant, product, brand, or terminal is not enabled. Contact Getnet.
Authentication	The terminal could not authenticate with the gateway. Check credentials and environment.
Integration / request	The request was malformed or rejected by validation. Fix the integration.
Platform / system	A server-side failure. Retry once; treat as an incident if it persists.

Host error envelope

Host errors (33-) originate at the SEP gateway. The field to branch on is error_code; reason_code carries the issuer reason on a decline.

Field	Description
`message`	Human-readable error message.
`name`	Error type, for example `GetnetTransactionError`.
`status_code`	HTTP status of the response, for example `400`.
`details[].status`	Transaction status, for example `DENIED`.
`details[].error_code`	The error code to branch on, for example `PAYMENTS-999`.
`details[].reason_code`	Issuer reason on a decline, for example `503`.

Host errors (`33-`) by HTTP status

HTTP 400 — `33-400`

`error_code`	Category	Description
`PAYMENTS-012`	Integration / request	Informed amount is greater than or equal to the transaction amount.
`PAYMENTS-013`	Integration / request	Invalid installment amount.
`PAYMENTS-015`	Cardholder / card	Contact the issuer.
`PAYMENTS-016`	Integration / request	Invalid NSU.
`PAYMENTS-019`	Cardholder / card	Invalid card issue date.
`PAYMENTS-020`	Cardholder / card	Invalid expiration date.
`PAYMENTS-024`	Transient — retry	Transaction reversed.
`PAYMENTS-025`	Cardholder / card	Invalid authentication.
`PAYMENTS-026`	Cardholder / card	Invalid authorization.
`PAYMENTS-029`	Integration / request	Invalid pre-authorization.
`PAYMENTS-044`	Integration / request	Format error.
`PAYMENTS-050`	Cardholder / card	Contact the institution.
`PAYMENTS-051`	Cardholder / card	Declined by a configured rule.
`PAYMENTS-054`	Duplicate / in progress	Confirmation pending.
`PAYMENTS-055`	Transient — retry	Transaction canceled.
`PAYMENTS-056`	Cardholder / card	Transaction not allowed in this cycle.
`PAYMENTS-058`	Transient — retry	Reverse the transaction.
`PAYMENTS-060`	Integration / request	Card required for the transaction.
`PAYMENTS-061`	Cardholder / card	Generic rejection.
`PAYMENTS-066`	Merchant / product config	Invalid payment method.
`PAYMENTS-068`	Cardholder / card	Invalid card digit.
`PAYMENTS-069`	Duplicate / in progress	Repeated transaction.
`PAYMENTS-070`	Cardholder / card	Card number does not match.
`PAYMENTS-072`	Integration / request	Transaction cannot be canceled.
`PAYMENTS-073`	Duplicate / in progress	Transaction already canceled.
`PAYMENTS-078`	Integration / request	Invalid data in the cancellation.
`PAYMENTS-079`	Integration / request	Invalid cancellation amount.
`PAYMENTS-080`	Cardholder / card	Invalid card.
`PAYMENTS-081`	Integration / request	Past the allowed date.
`PAYMENTS-082`	Integration / request	Invalid cancellation.
`PAYMENTS-083`	Cardholder / card	Use the debit function.
`PAYMENTS-084`	Cardholder / card	Use the credit function.
`PAYMENTS-085`	Duplicate / in progress	Transaction already performed.
`PAYMENTS-090`	Cardholder / card	Transaction not authorized by the card.
`PAYMENTS-091`	Integration / request	Outside the allowed period.
`PAYMENTS-093`	Duplicate / in progress	Authorization already processing.
`PAYMENTS-094`	Transient — retry	Authorization awaiting receipt confirmation.
`PAYMENTS-098`	Merchant / product config	Customer not registered.
`PAYMENTS-117`	Cardholder / card	Ask the cardholder to call the issuer.
`PAYMENTS-118`	Merchant / product config	Invalid card or product not enabled.
`PAYMENTS-999`	Transient — retry	Transaction not processed.
`GENERIC-400`	Cardholder / card	Invalid credit card.
`GENERIC-400`	Integration / request	Validation error.
`GENERIC-400`	Integration / request	Header validation.
`GENERIC-400`	Integration / request	Error requesting cancellation.
`GENERIC-400`	Platform / system	Service error.
`GENERIC-400`	Integration / request	Invalid parameter.
`GENERIC-400`	Integration / request	Invalid argument.
`GENERIC-400`	Merchant / product config	Card brand code not enabled.
`GENERIC-400`	Integration / request	Query validation error.

HTTP 401 — `33-401`

`error_code`	Category	Description
`GENERIC-401`	Authentication	Unauthorized.

HTTP 402 — `33-402`

`error_code`	Category	Description
`PAYMENTS-001`	Integration / request	Amount not provided.
`PAYMENTS-002`	Cardholder / card	Invalid card.
`PAYMENTS-003`	Cardholder / card	Expired card.
`PAYMENTS-004`	Integration / request	Invalid parameter.
`PAYMENTS-005`	Cardholder / card	Invalid security code.
`PAYMENTS-006`	Merchant / product config	Invalid brand.
`PAYMENTS-007`	Merchant / product config	Operation not allowed.
`PAYMENTS-008`	Integration / request	Invalid data.
`PAYMENTS-009`	Integration / request	Invalid minimum installment amount.
`PAYMENTS-010`	Integration / request	Invalid number of installments.
`PAYMENTS-011`	Integration / request	Number of installments exceeds the limit.
`PAYMENTS-014`	Merchant / product config	Installment payment not allowed.
`PAYMENTS-022`	Merchant / product config	Invalid currency code.
`PAYMENTS-023`	Merchant / product config	Brand does not belong to the network.
`PAYMENTS-030`	Cardholder / card	Error in user authentication.
`PAYMENTS-032`	Cardholder / card	Denied by the issuer.
`PAYMENTS-033`	Merchant / product config	Invalid establishment.
`PAYMENTS-034`	Merchant / product config	Request not authorized.
`PAYMENTS-036`	Integration / request	Invalid request identifier.
`PAYMENTS-037`	Duplicate / in progress	Transaction in progress.
`PAYMENTS-038`	Integration / request	Invalid transaction.
`PAYMENTS-039`	Integration / request	Invalid transaction amount.
`PAYMENTS-041`	Transient — retry	Redo the transaction.
`PAYMENTS-045`	Cardholder / card	Restricted card.
`PAYMENTS-046`	Cardholder / card	Lost card.
`PAYMENTS-047`	Cardholder / card	Stolen card.
`PAYMENTS-048`	Cardholder / card	Card not registered.
`PAYMENTS-049`	Cardholder / card	Transaction not allowed for this customer.
`PAYMENTS-052`	Duplicate / in progress	Duplicate transaction.
`PAYMENTS-053`	Cardholder / card	Blocked card.
`PAYMENTS-067`	Cardholder / card	Limit amount exceeded.
`PAYMENTS-077`	Cardholder / card	Invalid card number.
`PAYMENTS-096`	Cardholder / card	Credit exceeded.
`PAYMENTS-101`	Platform / system	Authorizer offline.
`PAYMENTS-102`	Cardholder / card	Customer without credit limit.
`PAYMENTS-103`	Cardholder / card	Transaction not authorized by the authorizing network.
`PAYMENTS-104`	Integration / request	Integration error.
`PAYMENTS-105`	Cardholder / card	Transaction not authorized.
`PAYMENTS-109`	Duplicate / in progress	There is a transaction to confirm.
`PAYMENTS-112`	Reference not found	No matching document to cancel.
`PAYMENTS-113`	Cardholder / card	Insufficient balance.
`PAYMENTS-114`	Cardholder / card	Exceeds the approval amount limit.
`PAYMENTS-115`	Cardholder / card	Exceeds the withdrawal frequency limit.
`PAYMENTS-116`	Cardholder / card	Authorization declined.
`SERVICE-402`	Platform / system	Error capturing credit transaction.
`SERVICE-402`	Platform / system	Error adjusting credit pre-authorization transaction.
`GENERIC-402`	Platform / system	Error creating deferred transaction.
`GENERIC-402`	Integration / request	Deferred payment expired.
`GENERIC-402`	Cardholder / card	Declined by fraud screening.
`GENERIC-402`	Integration / request	Invalid document.
`GENERIC-402`	Platform / system	Error canceling credit transaction.
`GENERIC-402`	Integration / request	Error validating business rules.

HTTP 403 — `33-403`

`error_code`	Category	Description
`GENERIC-403`	Merchant / product config	Payment method not allowed.
`GENERIC-403`	Merchant / product config	Card brand type not allowed.
`GENERIC-403`	Merchant / product config	Service not enabled.
`GENERIC-403`	Authentication	Invalid or already used token.
`GENERIC-403`	Authentication	Unauthorized error.
`GENERIC-403`	Merchant / product config	Pix product not enabled.

HTTP 404 — `33-404`

`error_code`	Category	Description
`PAYMENTS-043`	Reference not found	Record not found.
`PAYMENTS-057`	Reference not found	Transaction does not exist.
`PAYMENTS-076`	Reference not found	Transaction not available.
`PAYMENTS-095`	Reference not found	Authorization not found.
`GENERIC-404`	Reference not found	Error creating deferred transaction.
`GENERIC-404`	Reference not found	Transaction not found.
`GENERIC-404`	Reference not found	Record not found.

HTTP 409 — `33-409`

`error_code`	Category	Description
`GENERIC-409`	Integration / request	The request could not be processed due to conflicting parameters.

HTTP 412 — `33-412`

`error_code`	Category	Description
`GENERIC-412`	Integration / request	Parameter not found.
`GENERIC-412`	Integration / request	Parameter not defined.

HTTP 422 — `33-422`

`error_code`	Category	Description
`GENERIC-422`	Integration / request	Unprocessable entity.

HTTP 500 — `33-500`

`error_code`	Category	Description
`PAYMENTS-042`	Platform / system	Invalid response.
`PAYMENTS-059`	Transient — retry	Local network problem.
`PAYMENTS-062`	Platform / system	Institution temporarily out of operation.
`PAYMENTS-063`	Platform / system	System failure.
`PAYMENTS-064`	Platform / system	Database error.
`PAYMENTS-071`	Platform / system	Authorizer temporarily blocked.
`PAYMENTS-086`	Platform / system	Transaction error.
`PAYMENTS-099`	Platform / system	Authorizer not initialized.
`PAYMENTS-100`	Platform / system	Channel disconnected.
`PAYMENTS-107`	Transient — retry	Communication error.
`PAYMENTS-500`	Platform / system	Internal server error.
`GENERIC-500`	Platform / system	The server encountered an unexpected error.

HTTP 501 — `33-501`

`error_code`	Category	Description
`GENERIC-501`	Platform / system	Invalid response from the upstream server.

HTTP 503 — `33-503`

`error_code`	Category	Description
`PAYMENTS-021`	Transient — retry	Issuer system unavailable — try again.
`GENERIC-503`	Transient — retry	The server cannot handle the request right now — try later.

HTTP 504 — `33-504`

`error_code`	Category	Description
`PAYMENTS-031`	Transient — retry	Time exceeded (timeout).
`PAYMENTS-089`	Transient — retry	Internal timeout.
`GENERIC-504`	Transient — retry	Connection timeout.

Card / EMV errors (`1-`)

Origin: the EMV kernel and terminal hardware. The Read type column groups codes by how the card was presented; Retry marks codes the SDK can retry, and Fallback marks the read method to fall back to. Codes marked Internal are not shown to the cardholder and usually need Getnet support.

Constant	Result code	Read type	Retry	Fallback	Description
`CTLSFALLBACK`	`1-53`	Contactless (NFC)	Yes	Contactless	Could not read by contactless. Insert the chip or swipe the stripe. Normal fallback.
`ERRCTLSS`	`1-33` (mag `1-08`)	Contactless (NFC)	Yes	—	Error reading by contactless. Try the chip or the stripe.
`CTLSSPROBLEMS`	`1-33` (mag `1-08`)	Contactless (NFC)	Yes	Contactless	Problem with the contactless read. Try again or insert the card.
`CTLSSMULTIPLE`	`1-21`	Contactless (NFC)	—	—	Multiple cards detected. Present a single card to the reader.
`CTLSSAPPNAV`	`1-50`	Contactless (NFC)	Yes	—	Card does not support contactless. Insert the chip.
`CTLSSAPPNAUT`	`1-50`	Contactless (NFC)	Yes	—	Contactless not authorized for this card. Insert the chip.
`CTLSSINVALIDAT`	`1-34`	Contactless (NFC)	Yes	Contactless	Contactless card not valid (expired or inactive). Contact the bank.
`CTLSSEXTCVM`	`1-21`	Contactless (NFC)	Yes	—	Card requires a PIN. Insert the chip.
`CARDBLOCKED`	`1-34`	Chip card	—	—	Card is blocked. Contact the bank.
`CARDINV`	`1-21`	Chip card	—	—	Card is not valid. Try another card.
`CARDINVALIDAT`	`1-34`	Chip card	Yes	Chip	Card expired or not yet active. Contact the bank.
`CARDNOTEFFECT`	`1-21`	Chip card	—	—	Card not yet valid. Contact the bank.
`CARDINVDATA`	`1-21`	Chip card	—	—	Could not read the chip data. Try again or use another method.
`CARDAPPNAV`	`1-50`	Chip card	Yes	—	Card not compatible with this terminal. Try another card.
`CARDAPPNAUT`	`1-21`	Chip card	—	—	Card did not authorize the transaction. Contact the bank.
`CARDPROBLEMS`	`1-21`	Chip card	Yes	Chip	Problem reading the chip. Clean the card and try again.
`DUMBCARD`	`1-36`	Chip card	Yes	Chip	Card has no chip. Swipe the magnetic stripe.
`ERRFALBACK`	`1-36`	Fallback	Yes	Chip	Could not read the chip. Swipe the magnetic stripe.
`NOCARD`	`1-36`	Reading	Yes	Contactless	No card detected. Tap, insert, or swipe the card.
`TIMEOUT`	`1-02`	Reading	—	—	The wait time expired. Try again. Handled as a cancellation.
`CANCELED`	`1-02`	Operation	—	—	The transaction was canceled by the operator or customer.
`ERRPIN`	`1-21`	PIN	—	—	Error entering the PIN. Check and try again.
`NOBALANCE`	`1-21`	Authorization	—	—	Insufficient balance. Try another card.
`LIMITEXC`	`1-21`	Authorization	—	—	Amount exceeds the card limit. Contact the bank.
`LOCKED`	`1-21`	Terminal	—	—	Terminal is locked. Collect the serial number and contact Getnet.
`TABLE_ERROR`	`1-21`	Internal	—	—	Error in the EMV configuration tables (AID/terminal) loaded in the kernel.
`NO_MATCH`	`1-21`	Internal	Yes	—	No card AID matches the AIDs configured on the terminal.
`INVPARM`	`1-21`	Internal	—	—	Invalid parameter sent to the EMV kernel (programming error).
`EXECERR`	`1-21`	Internal	—	—	Internal execution error in the EMV kernel.
`TABERR`	`1-21`	Internal	—	—	Error accessing an internal EMV table.
`UNKNOWNSTAT`	`1-21`	Internal	—	—	Unknown state returned by the kernel.
`RSPERR`	`1-21`	Internal	—	—	Error in the response received from the host or authorizer.
`COMMTOUT`	`1-21`	Internal	—	—	Communication timeout with the host. Check the transaction before retrying a charge.
`INTERR`	`1-21`	Internal	Yes	—	Internal kernel error. Emitted on every `onPanic` and on the kernel’s `onError(INTERR)`.
`MCDATAERR`	`1-33` (mag `1-08`)	Internal	Yes	—	Error in the data read from the magnetic stripe.
`PINBUSY`	`1-21`	Internal	—	—	The PIN module is busy processing another request.
`ERRCARD`	`1-36`	Internal	Yes	Chip	Generic card error with no specific classification.
`CARDERRSTRUCT`	`1-21`	Internal	Yes	Chip	Error in the chip structure (malformed TLV).

Warm-up errors

The SDK reports these before a sale, through setOnWarmUpStatus.

Code	Constant	Category	What it means	Action
`-1`	`ERROR_NO_CONNECTION`	Transient — retry	No network connection.	Check Wi-Fi or mobile data and retry on the warm-up screen.
`-2`	`ERROR_TIMEOUT`	Transient — retry	Network timeout during warm-up.	Check the connection and retry. If it persists across terminals, escalate.
`-3`	`ERROR_SSL`	Platform / system	SSL/TLS handshake failure.	Check the device date and time; if correct, contact Getnet.
`-4`	`ERROR_CONNECT`	Transient — retry	Could not connect to the host.	Check the connection and environment; retry.
`-5`	`ERROR_SOCKET`	Transient — retry	Socket error during transfer.	Retry; if it persists, escalate (unstable connection).
`400`	`HTTP_BAD_REQUEST`	Integration / request	Warm-up or config request rejected as malformed.	Contact Getnet — credentials or `terminalCode` configuration.
`401`	`HTTP_UNAUTHORIZED`	Authentication	Invalid `client_id` / `client_secret` (OAuth2 failed).	Contact Getnet — wrong credentials or environment.
`404`	`HTTP_NOT_FOUND`	Reference not found	Terminal or config resource not found.	Collect the terminal code; contact Getnet — the terminal may not be registered.
`422`	`HTTP_UNPROCESSABLE`	Integration / request	Config request semantically rejected.	Contact Getnet — sub-merchant or terminal config values.

Environments

Environment	Build	Base URL
Pre-production / Development	`debug`	`https://api.pre.globalgetnet.com/`
Homologation (HML)	`hml`	`https://api.sbx.globalgetnet.com/`
Production	`release`	`https://api.globalgetnet.com/`

Payment method mapping

How each payment method maps from the SDK setup to the SEP wire value and application type.

Method	SDK setup	SEP wire	App type
Credit	`BrSaleSetup.Credit` / `IBrSaleMethod.CreditCard`	`DIRECT_CREDIT`	`01`
Debit	`BrSaleSetup.Debit` / `IBrSaleMethod.DebitCard`	`DIRECT_DEBIT`	`02`
Voucher	`BrSaleSetup.Voucher` / `IBrSaleMethod.Voucher`	`DIRECT_VOUCHER`	`12`
Pix	`BrSaleSetup.Pix` / `IBrSaleMethod.Pix`	QR-code flow (not the card body)	`30`

Services the SDK calls

You do not call these services directly — the SDK does. They are listed to explain where host (33-) and warm-up errors originate.

Method	Path	Purpose
POST	`dpm/payments-gwproxy/v2/payments`	Create a payment (sale / single step). The main card-present transaction.
POST	`dpm/payments-gwproxy/v2/payments/cancel`	Cancel or refund a payment.
POST	`dpm/payments-gwproxy/v2/payments/qrcode/pix`	Generate a Pix QR Code.
GET	`dpm/hub-payment-info/v1/payments/info/{payment_id}`	Query a transaction or Pix status. Use after a timeout.
POST	`authentication/oauth2/access_token`	OAuth2 token (`client_credentials`), injected as Bearer on every SEP call.
POST	`tms/terminal-management-adp/v1/configuration`	Fetch the terminal configuration during warm-up.
PATCH	`tms/terminal-management-adp/v1/configuration/confirmation`	Confirm the terminal configuration.

Troubleshooting — diagnose a failure and decide what to do about it.
Transaction result reference — the result fields and payloads returned to your app.
Initialization reference — the warm-up states and how to recover from Failure.

Error Codes Reference

Result code scheme

Examples

Cause categories

Host error envelope

Host errors (33-) by HTTP status

HTTP 400 — 33-400

HTTP 401 — 33-401

HTTP 402 — 33-402

HTTP 403 — 33-403

HTTP 404 — 33-404

HTTP 409 — 33-409

HTTP 412 — 33-412

HTTP 422 — 33-422

HTTP 500 — 33-500

HTTP 501 — 33-501

HTTP 503 — 33-503

HTTP 504 — 33-504

Card / EMV errors (1-)