Skip to main content

Error codes

In the world of payment processing, errors can occur during transactions. When a transaction fails, it's essential to understand the associated error code and message to troubleshoot and resolve the issue. The IXOPAY platform provides comprehensive error code documentation to assist you in handling errors effectively. This article focuses on the IXOPAY platform's errorCode and errorMessage.


If the error is produced by any subsequent system (bank, PSP, PayPal, etc.), the error element will also contain the adapterCode and adapterMessage, reflecting directly the response of those systems.


The error codes in the IXOPAY platform documentation are organized into different groups, reflecting the phase in which an error occurred. These groups include:

  • General errors and validation errors
  • Payment errors
  • Network errors
  • Post-processing errors
  • Schedule API errors
  • Status API errors

By categorizing errors, you can quickly identify the nature of the issue and take appropriate action to resolve it.


While there can be thousands of different adapter error codes depending on the configured connectors, this documentation focuses on the consolidated error codes provided by IXOPAY platform. These consolidated error codes are typically the ones you'll want to consider for effective error handling.

Within each group, you will find detailed information about specific error codes, including their meanings, potential causes, and recommended actions.

Default message

Please note that the "Default message" column provides the standard error message associated with each error code. However, in some cases, the actual message returned in the API response may be expanded with additional information or entirely changed based on specific circumstances. For reliable error handling in your application, always depend on the error code rather than the error message.

General errors and validation errors

CodeDefault message1Description
1000Request failedSome fundamental error in your request.
1001Invalid responseThe upstream system responded with an unknown response.
1002Invalid request dataRequest data are malformed or missing.
1003Processing errorTransaction could not be processed.
1004Invalid signatureThe request signature you provided was wrong.
1005Invalid request bodyThe request body you provided was malformed or invalid.
1006Logical errorPreconditions failed, for example trying to capture on a failed authorize.
1007Invalid configurationSomething is wrong with your configuration, please contact your integration engineer.
1008Unexpected system errorAny unexpected system error.
1009Too many requestsRate limit has been exceeded.
1010System maintenanceThe system is currently undergoing scheduled maintenance. Please try again later.
9999Unknown errorWe received an error which is not yet mapped to a better error code.

Payment errors

CodeDefault message1Description
2001Account closed externallyThe customer cancelled permission for his payment instrument externally.
2002User cancelledTransaction was cancelled by customer.
2003Transaction declinedTransaction declined by upstream system/bank.
2004Quota regulationSome limit reached.
2005Transaction expiredCustomer took to long to submit his payment info.
2006Insufficient fundsCard limit reached.
2007Incorrect payment info
2008Invalid cardCard is invalid.
2009Expired card
2010Fraudulent card
2011Unsupported card
2012Transaction cancelled
2013Risk check blockThis error can occur due to a risk block triggered by either the Risk Engine or the upstream PSP.
2014Pickup card
2015Lost cardCard is claimed as lost.
2016Stolen card
2017IBAN invalid
2018BIC invalid
2019Customer data invalid
2020CVV required
20213D-Secure Verification failed
20223D-Secure Soft declined

Network errors

CodeDefault message1Description
3001TimeoutA timeout occurred while calling an upstream service.
3002Not AllowedDisallowed method called on upstream service.
3003Temporary unavailableAn upstream service is temporarily unavailable.
3004Duplicate transaction ID
3005Communication errorOther upstream communication errors.

Post-processing errors

CodeDefault message1Description
4001Chargeback revertedChargeback was reverted.
4002Payment disputeA dispute was filed, see the upstream system (e.g. PayPal) for details.

Schedule API errors

CodeDefault message1Description
7001schedule request is invalid
7002schedule request failed
7005scheduleAction is not valid
7010registrationId is required
7020registrationId is not valid
7030reference transaction not a registerThe registrationId/referenceUuid must point to a register or a debit-with-register or a preauthorize-with-register.
7035initial transaction is not a registerThe transaction for starting a schedule must be a register, a debit-with-register or a preauthorize-with-register.
7036invalid initial periodThe period between the initial and second transaction must be greater than 24 hours.
7040The scheduleId is not valid or does not match to the connector
7050The startDateTime is invalid or older than 24 hours
7060The continueDateTime is invalid or older than 24 hours
7070The status of the schedule is not valid for the requested operation

Status API errors

CodeDefault message1Description
8001Transaction not foundNo transaction was found for this specific connector determined by the apiKey.