#Error Codes

This document provides a comprehensive list of error codes and descriptions for the Acquiring API and SDK. These codes help developers identify and resolve issues during integration and transaction processing.

1. Error Handling Principles

  • Retry Strategy: For System & Network errors (codes 12xxx), it is recommended to implement a retry mechanism with exponential backoff.
  • Idempotency: If you receive error 12006, it indicates a conflict where a request with an existing merchant_request_id was sent with different parameters.
  • Source of Truth: While API responses provide immediate feedback, always use Webhooks as the final source of truth for transaction statuses (SUCCEEDED or FAILED).
  • Async Processing: Payment processing (especially with 3DS) is asynchronous; do not rely solely on frontend responses for fulfillment.

2. Payment & Refund Errors

These errors are related to the lifecycle and logic of a transaction.

Error CodeError NameDescription / Meaning
8301NO_PAYMENT_ORDERThe specified payment order could not be found.
8302INVALID_PAYMENT_TYPEThe payment type provided is invalid.
8303INVALID_PRODUCT_ITEMThe product or item information is invalid.
8304NO_CARD_WITH_PAYMENTNo card information is associated with this payment.
8305INVALID_PAYMENT_METHODThe payment method type is not supported.
8306PAYMENT_EXPIRE_FOR_OPThe payment has expired and cannot undergo the requested operation.
8307INVALID_PAYMENTThe payment is in an invalid state for the requested operation.
8390NO_PAYMENT_RESPONSENo response was received from the upstream payment provider.
8391NO_PAYMENT_RESPONSE_DATAUpstream provider responded, but mandatory data is missing.
8400REFUND_EXCEED_LIMITThe refund amount exceeds the allowed limit or original transaction balance.

3. Checkout Session Errors

Specific to the Hosted Checkout Page integration flow.

Error CodeError NameDescription / Meaning
8500CHECKOUT_SESSION_INVALID_OPInvalid operation for the current status of the checkout session.
8501CHECKOUT_SESSION_INVALID_DATAThe checkout session contains invalid data or configuration.

4. System & Network Errors

Underlying infrastructure or connectivity issues.

Error CodeError NameDescription / Meaning
12000UNKNOWN_ERRORAn unknown system error occurred. Please try again later.
12001RARE_ERRORA rare internal error occurred. Please contact tech support.
12002NETWORK_CONNECTION_ERRORNetwork instability detected.
12003READ_TIMEOUT_ERRORThe request timed out. Check transaction status via GET API.
12004UPSTREAM_GATEWAY_ERRORUpstream gateway error. This is usually retryable.
12005CONFIG_ERRORSystem configuration error. Please contact tech support.
12006IDEM_REQ_PARAMS_CHANGEDIdempotency Conflict: Parameters changed for the same request key.
12007REPEATED_REQUESTSrepeated request.

5. Input Validation Errors

Errors triggered when the request payload does not meet API specifications.

Error CodeError NameDescription / Meaning
13001INPUT_PARAM_NULLA required input parameter is null.
13002INPUT_PARAM_INVALIDAn input parameter is formatted incorrectly.
13003REQUIRED_FIELD_NULLSpecific required fields are missing from the request.
13004INPUT_PARAM_NOT_NEGATIVEThe value (e.g., amount) cannot be negative.
13005PARAMS_ALL_EMPTYAt least one parameter must be provided; the request cannot be empty.

6. Data Integrity Errors

Error CodeError NameDescription / Meaning
14001OBJECT_NOT_EXISTThe requested object (ID) does not exist in the database.
14002OBJECT_NOT_UNIQUEData integrity issue: multiple objects found where only one was expected.
14004DATA_NOT_CONSISTENTInconsistent data state detected.
14005DATA_RESOLVE_ERRORFailed to resolve or deserialize data to the expected type.
14006ENUM_DATA_CONVERSION_ERRORFailed to convert data to the required enumeration type.
14007NUMBER_CONVERSION_ERRORFailed to convert the provided value to a numeric format.