# 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](https://docs.globalgetnet.com/en/products/in-store-payments/getnet-toolbox?doc=sdk-wl-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. |

<Callout type="note">

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.

</Callout>

## 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. |

## Related resources

* [Troubleshooting](https://docs.globalgetnet.com/en/products/in-store-payments/getnet-toolbox?doc=sdk-wl-troubleshooting) — diagnose a failure and decide what to do about it.
* [Transaction result reference](/en/getnet-toolbox/sdk-white-label/reference-sdk/transaction-result) — the result fields and payloads returned to your app.
* [Initialization reference](/en/getnet-toolbox/sdk-white-label/reference-sdk/initialization) — the warm-up states and how to recover from `Failure`.