Skip to content

Error codes

This section provides details of errors that could occur when running ActiveServer.

Authentication API Error Codes Overview

In ActiveServer, there are 6 error code categories:

  1. 3DS Error Codes
    Error codes in this category are defined by the EMVCo Core Protocol specifications. Error codes defined here can be returned from either the 3DS Server (ActiveServer), DS, ACS or the 3DS SDK. The component which identified the error will return the error response and set the errorComponent field as itself in the JSON response (for example, if an error was identified by the DS, it will set the errorComponent to D). If the error was identified in a component that is outside of ActiveServer, it will forward the same error JSON to the 3DS Requestor. The errorMessageType, errorDetail and errorDescription fields can be used to interpret the message that was erroneous. Refer to the ApiErrorResponse model for description of each field.
  2. Transaction Error Codes
    Transaction error codes defined by ActiveServer. The errorComponent field will be S at all times because the error was identified by the 3DS Server.
  3. General Error Codes
    Errors that does not fall into either 3DS Error Codes or Transaction Error Codes are returned as a General Code. These error codes may also be returned from the Admin API. Check the Auth API Description for descriptions related to the Authentication API.
  4. Security Error Codes
  5. User Error Codes
  6. Setup Error Code


  • Only error codes in the 3DS Error Codes, Transaction Error Codes and General Error Codes categories can be returned from the Authentication API(/api/v2/auth/***).
  • Security Error Codes, User Error Codes or Setup Error Code will not be returned from the Authentication API.
  • For each error code, an associated HTTP Status Code from the table below will be returned.
  • Description contains the possible scenario in which the error code may be returned, and for some error codes common solutions are also highlighted.


    Error codes which have the tag Not returned in Auth API v2 will not be returned as a response for /api/v2/auth/***.

3DS Error Codes (101 ~ XXX)

CodeNameHTTP Status CodeDescription
101MESSAGE_RECEIVED_INVALID400Received message is invalid. Message is not AReq, ARes, CReq, CRes, PReq, PRes, RReq, or RRes. For example, 3DS Server receives an message from DS as a response to AReq that is not ARes or Erro message.
400Unsupported message version number. Message Version Number received is not valid for the receiving component. For example, DS sends a messageVersion field set to an invalid value, or value that is not supported by the ACS.
103SENT_MESSAGES_LIMIT_EXCEEDED500Message sent exceeds the limit. Exceeded maximum number of PReq messages sent to the DS. Not returned in Auth API v2. (PReq is outside the authentication flow and is an internal process between ActiveServer and DS).
201REQUIRED_DATA_ELEMENT_MISSING400A message element required as defined according the specification is missing. This error code will be returned if any of the fields marked as required is missing in the request. For example, messageCategory is missing in the call to /api/v2/auth/brw. If the errorMessageType is AReq or missing, and errorComponent is S then the request from the 3DS Requestor is missing the required fields defined by the Authentication API. Please double check the fields returned in errorDetail is present in the request.
400Message extension that is critical is not present. May be returned from DS or ACS if the messageExtension field is missing an identifier.
400Data element is not in the required format or value is invalid as defined according the specification. This error code will be returned if any of the fields in the request is not well formatted. For example, purchaseAmount is not numeric in the call to /api/v2/auth/brw. If the errorMessageType is AReq or empty, and errorComponent is S then request from the 3DS requestor is not matching the fields defined by the Authentication API. Please double check the formatting of fields returned in errorDetail is present in the request.
204DUPLICATE_DATA_ELEMENT400Found duplicate data elements in the request.
301TRANSACTION_ID_NOT_RECOGNISED400Transaction ID received is not valid for the receiving component. For example, 3DS Requestor sets the threeDSSereverTransID in the /api/v2/auth/brw that is different from the one returned by /api/v2/auth/brw/init.
302DATA_DECRYPTION_FAILURE500Data could not be decrypted by the receiving system due to technical or other reason. DS may return this error code if data decryption of the SDK Encrypted data failed.
303ACCESS_DENIED_INVALID_ENDPOINT401Endpoint for the API request is invalid. Check the requesting URL. Reference number does not represent the participating component (for example, acsReferenceNumber sent from ACS to DS is invalid).
304ISO_CODE_INVALID400ISO code not valid according to ISO tables (for either country or currency).
305TRANSACTION_DATA_NOT_VALID400Transaction data is invalid. Please refer to the error description to find out why the transaction data was invalid.
400Merchant category code is invalid. Invalid MCC received in the AReq message and DS may throw this error back to ActiveServer.
307SERIAL_NUMBER_NOT_VALID500Serial number is invalid. Not returned in Auth API v2. (PReq is outside the authentication flow and is an internal process between ActiveServer and DS).
402TRANSACTION_TIMED_OUT408Transaction has timed out. In ActiveServer, this error code is returned if transaction timed out during sending the request to the DS (for example, sending AReq to the DS).
403TRANSIENT_SYSTEM_FAILURE500System has failed for a short period. For example, a slowly processing back-end system.
404PERMANENT_SYSTEM_FAILURE500System has failed permanently. For example, a critical database cannot be accessed. May be returned if DS settings is not properly configured in ActiveServer such as client certificate for the DS is not installed in ActiveServer.
405SYSTEM_CONNECTION_FAILURE500Failed to connect to the system. For example, the sending component is unable to establish connection to the receiving component.

DS Specific Error Codes

In addition to the EMVCo defined 3DS error codes, there may be additional error codes defined by the card schemes which may be returned by the card scheme's directory server in certain scenarios.

UnionPay International

The following special error codes are defined in the UnionPay International specifications.

CodeNameHTTP Status CodeDescription
911Data fields relevance check failed500ECI value and AV appearance are inconsistent with transaction status
912Duplicated transaction ID500Transaction ID should be unique for each AReq request

Transaction Error Codes (1001 ~ 1027)

CodeNameHTTP Status CodeDescription
1000DIRECTORY_SERVER_NOT_AVAILABLE500If any errors occurred during the connection to Directory Server this error code may be returned. Error code 402 is returned instead if the reason of the connection error was because of timeout.
1001DIRECTORY_SERVER_NOT_FOUND500No Directory Server was found for a card scheme associated with the PAN. May be returned if Default URL is empty in the Administration UI for a card scheme. Make sure the Default URL is configured in the ActiveServer admin UI dashboard.
1002ERROR_SAVE_TRANSACTION500Error occurred while saving transaction. May be returned if transaction details is failed to be saved into the database during the authentication.
1003ERROR_SAVE_TRANSACTION_MESSAGE500Error returned while saving transaction message. Not returned in Auth API v2. But, if an error occurred while saving a raw message (for example, raw AReq JSON message), it will not fail the transaction.
1004UNHANDLED_EXCEPTION500Unhandled exception occurred during the transaction. Please check the error description or report error logs for further investigation.
1005PAN_NOT_PARTICIPATING400Primary Account Number (PAN) is not participating. Not returned in Auth API v2.
1009MERCHANT_INTERFACE_DISABLED400The interface is disabled for this merchant. Not returned in Auth API v2. MERCHANT_ID_THREEDS_REQUESTOR_ID_INVALID (1026) will be returned instead.
1011INVALID_LICENSE403Invalid ActiveServer license in use. Please resolve this licensing issue with GPayments as soon as possible.
1013INVALID_TRANSACTION_ID400Transaction ID of 3DS Server is not recognised. This error code may be returned if threeDSServerTransID is invalid in the given request.
1014INVALID_REQUESTOR_TRANSACTION_ID400Transaction ID of 3DS Requestor is not recognised. May be returned if the threeDSRequestorTransID is not in UUID format.
1015THREEDS_REQUESTOR_NOT_FOUND400Invalid 3DS Requestor ID or Merchant ID. Not returned in Auth API v2. MERCHANT_ID_THREEDS_REQUESTOR_ID_INVALID (1026) will be returned when client certificate or merchantId is invalid.
1016MISSING_REQUIRED_ELEMENT400Required element missing. May be returned if required fields in the authentication API is missing.
1018ELEMENT_NOT_DEFINED400Message element not a defined message. Not returned in Auth API v2.
1019PROTOCOL_OLD500Protocol version is too old. Not returned in Auth API v2.
1020ERROR_TRANSMISSION_DATA500Errors in data transmission. It will be returned when there is an error sending a request or receiving a response from the DS. If the reason for the error is request being timed out, then it will return error code TRANSACTION_TIMED_OUT (402) instead. If the connection is not established in the first place, then it will return DIRECTORY_SERVER_NOT_AVAILABLE (1000).
1021PRIOR_TRANS_ID_NOT_FOUND400Prior Transaction ID could not be found in the database, or is invalid. This error may be returned if priorTransID given in the authentication request is not in a valid UUID format. priorTransID should contain the threeDSServerTransID used in the same cardholder's last transaction.
1022INVALID_FORMAT400Format of one or more elements is invalid according to the specification. May be returned if fields in the authentication API has an invalid format. For example, browserInfo given in /api/v2/auth/brw is not in the same format as the one collected by ActiveServer.
1023CARD_RANGE_IS_NOT_VALID400Card range provided is invalid. Not returned in Auth API v2.
1024CACHE_UPDATE_IS_DISABLE500Cache update is disabled. Not returned in Auth API v2.
1025CACHE_REFRESH_INTERVAL_IS_NOT_SET500Cache refresh interval is not set. Not returned in Auth API v2.
400Invalid merchantId is given to the authentication request. Make sure that merchantId provided in the request matches the client certificate for the merchant, or the merchantToken if master client certificate is used. If you have revoked the client certificate, make sure to update the client certificate or the merchantToken in the API request.
1027UNSUPPORTED_API_VERSION403This error may be thrown if the API version you are trying to make a request to is not supported. For example, API version 1 is not supported for ActiveServer using AWS KMS.

General Error Codes (2000 ~ 2009)

CodeNameHTTP Status CodeDescriptionAuth API Description
2000NOT_FOUND404Resource not found.Not returned in Auth API v2.
2001DUPLICATE_RECORD409Record already exists.Not returned in Auth API v2.
2002VALIDATION_ERROR400Invalid inputs.May be returned if the request is not properly formatted as a JSON.
2003INVALID_REQUEST400Invalid request.Not returned in Auth API v2.
2004CONCURRENCY_FAILURE409Failed to update node.Not returned in Auth API v2.
2005ACCESS_DENIED401Access is denied.Check the error detail for more description for why the access was denied.
2006METHOD_NOT_SUPPORTED405Request HTTP method is not supported.Not returned in Auth API v2
2007INTERNAL_SERVER_ERROR500Internal server error.Internal server error has occurred in ActiveServer, may be due to some configuration issue or setup issue. Please refer to the error description for more details.
2008DATA_INTEGRITY_VIOLATION_ERROR400A specified value violated the integrity constraints. May occur if attempting to insert of update results in violation of an integrity constraint. For example, unique primary keys are not inserted into the table.Not returned in Auth API v2
2009SESSION_TIMED_OUT408Session has timed out.May be returned if the transaction has already finished.

Security Error Codes (3001 ~ 3024)

CodeNameHTTP Status CodeDescription
3001JDK_NOT_SUPPORT_SHA224WITHRSA500JDK used does not support the SHA224 with RSA algorithm.
3002NO_SUCH_ALGORITHM500No such algorithm.
3003INVALID_CERT400The certificate's public key is not compatible with the corresponding private key.
3004INVALID_CHAIN400ActiveServer is unable to build the full certificate chain as one or more intermediate certificates cannot be found in the CA certificate store. You should either install/import a certificate which contains the full chain or install the missing intermediate certificates before attempting again.
3005NO_PRIVATE_KEY_FOUND400No private key found.
3006INVALID_CERTIFICATE_CONTENT400Invalid certificate content
3007CERTIFICATE_IO_READ400Unable to read certificate.
3008SUCH_PROVIDER_EXCEPTION500No such provider exception.
3009NO_KEY400The certificate could not be installed because this object does not have an existing key.
3010CERTIFICATE_CHAIN_BAD_FORMAT400Certificate chain has invalid format.
3011MISMATCHED_PASSWORDS400Password fields do not match.
3012IMPORT_CERTIFICATE400No certificate found for the importing certificate. Please import client certificate.
3013IMPORT_NO_CERTIFICATE400There is no certificate to export.
3014FAILED_TO_INITIALIZE500Failed to initialise.
3015ENCRYPTION_FAIL500Failed to encrypt.
3016DECRYPTION_FAIL500Failed to decrypt.
3017INVALID_HSM_PROVIDER500The specified provider name for hardware encryption is not supported
3018INVALID_PKCS11_CONFIG500Invalid PKCS11 config path
3019FAILED_TO_INITIALIZE_PKCS11500Failed to initialise PKCS11.
3020IMPORT_FAIL500Failed to import.
3021NOT_SUPPORTED_IBM_PROVIDER500Only SUN provider is supported.
3022UNABLE_TO_LOAD_KEYSTORE500Loading keystore failed.
3023UNABLE_TO_LOAD_CERTIFICATE500Loading certificate failed.
3024INVALID_KEY_SIZE500Key size is invalid.

User Error Codes (4000 ~ 4032)

CodeNameHTTP Status CodeDescription
4000DUPLICATE_EMAIL400E-mail already in use.
4001LAST_ADMIN_DELETE_NOT_ALLOWED400You need to be at least a System Admin user to perform this action.
4002ACCOUNT_IS_LOCKED401Your account is locked.
4003ACCOUNT_IS_DISABLED401Your account is disabled.
4004ACCOUNT_WILL_BE_LOCKED401Your account will be locked after another wrong try. If you have been forgotten your password please click on "Lost your password"
4005ACCOUNT_WAS_LOCKED401Password has been locked for 1 hour.
4006ACCOUNT_IS_INACTIVE401Your account was not activated.
4007PASSWORD_POLICY_MATCH401The password should be minimum eight characters, with at least one letter and one number.
4008LOGIN_ALREADY_IN_USE401Username already in use.
4009EMAIL_ALREADY_IN_USE401Email already in use.
4010INVALID_TOTP_CODE400Invalid TOTP authentication code.
4011EMAIL_SENDING_FAILED400Failed to send email.
4012EMAIL_NOT_REGISTERED400Your email is not registered.
4014FAILED_TO_CREATE_ACCOUNT500Failed to create the account.
4015TWO_FA_MANDATORY400Using two factor login is mandatory.
4016PASSWORD_EXPIRED403The password for user was expired.
4017PASSWORD_EXPIRED_WARNING403The password for user is going to be expired on.
4018PASSWORD_HISTORY_MATCHED403The password matched with the previous historical passwords.
4019INVALID_TOKEN400An invalid token.
4020INVALID_HSM_PIN400Invalid HSM Pin.
4021INVALID_PASSWORD400Invalid password.
4022EMAIL_INVALID_ACTIVATION403Account activation code is invalid.
4026REMOVE_USER_ADMIN_ROLE_FROM_USER_NOT_ALLOWED400Your instance always requires at least one User admin role.
4027DELETE_THE_ONLY_USER_WITH_USER_ADMIN_ROLE_NOT_ALLOWED403Your instance always requires at least one User admin role.
4029DELETE_LOGGED_IN_USER_NOT_ALLOWED403Cannot delete the currently logged in user.
4031USERNAME_OR_PASSWORD_INCORRECT403Username or password is incorrect.
4032PASSWORD_RESET_LIMIT_REACHED400Password reset cannot be requested more than once every 15 mins.

Setup Error Code (5000)

CodeNameHTTP Status CodeDescription
5000SETUP_NOT_ALLOWED500Setup is not allowed.