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:
- 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 theerrorComponent
field as itself in the JSON response (for example, if an error was identified by the DS, it will set theerrorComponent
toD
). If the error was identified in a component that is outside of ActiveServer, it will forward the same error JSON to the 3DS Requestor. TheerrorMessageType
,errorDetail
anderrorDescription
fields can be used to interpret the message that was erroneous. Refer to theApiErrorResponse
model for description of each field. - Transaction Error Codes
Transaction error codes defined by ActiveServer. TheerrorComponent
field will beS
at all times because the error was identified by the 3DS Server. - 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. - Security Error Codes
- User Error Codes
- Setup Error Code
Additionally,
- 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.
Tip
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)¶
Code | Name | HTTP Status Code | Description |
---|---|---|---|
101 | MESSAGE_RECEIVED_INVALID | 400 | Received 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. |
102 | MESSAGE_VERSION_NUMBER_ NOT_SUPPORTED | 400 | Unsupported 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. |
103 | SENT_MESSAGES_LIMIT_EXCEEDED | 500 | Message 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). |
201 | REQUIRED_DATA_ELEMENT_MISSING | 400 | A 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. |
202 | CRITICAL_MESSAGE_ EXTENSION_NOT_RECOGNISED | 400 | Message extension that is critical is not present. May be returned from DS or ACS if the messageExtension field is missing an identifier. |
203 | FORMAT_OF_ONE_OR_MORE _DATA_ELEMENTS_IS_INVALID _ACCORDING_TO_THE_SPECIFICATION | 400 | Data 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. |
204 | DUPLICATE_DATA_ELEMENT | 400 | Found duplicate data elements in the request. |
301 | TRANSACTION_ID_NOT_RECOGNISED | 400 | Transaction 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 . |
302 | DATA_DECRYPTION_FAILURE | 500 | Data 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. |
303 | ACCESS_DENIED_INVALID_ENDPOINT | 401 | Endpoint 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). |
304 | ISO_CODE_INVALID | 400 | ISO code not valid according to ISO tables (for either country or currency). |
305 | TRANSACTION_DATA_NOT_VALID | 400 | Transaction data is invalid. Please refer to the error description to find out why the transaction data was invalid. |
306 | MERCHANT_CATEGORY_CODE_MCC_ NOT_VALID_FOR_PAYMENT_SYSTEM | 400 | Merchant category code is invalid. Invalid MCC received in the AReq message and DS may throw this error back to ActiveServer. |
307 | SERIAL_NUMBER_NOT_VALID | 500 | Serial number is invalid. Not returned in Auth API v2. (PReq is outside the authentication flow and is an internal process between ActiveServer and DS). |
402 | TRANSACTION_TIMED_OUT | 408 | Transaction 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). |
403 | TRANSIENT_SYSTEM_FAILURE | 500 | System has failed for a short period. For example, a slowly processing back-end system. |
404 | PERMANENT_SYSTEM_FAILURE | 500 | System 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. |
405 | SYSTEM_CONNECTION_FAILURE | 500 | Failed 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.
Code | Name | HTTP Status Code | Description |
---|---|---|---|
911 | Data fields relevance check failed | 500 | ECI value and AV appearance are inconsistent with transaction status |
912 | Duplicated transaction ID | 500 | Transaction ID should be unique for each AReq request |
Transaction Error Codes (1001 ~ 1027)¶
Code | Name | HTTP Status Code | Description |
---|---|---|---|
1001 | DIRECTORY_SERVER_NOT_FOUND | 500 | No 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. |
1002 | ERROR_SAVE_TRANSACTION | 500 | Error occurred while saving transaction. May be returned if transaction details is failed to be saved into the database during the authentication. |
1003 | ERROR_SAVE_TRANSACTION_MESSAGE | 500 | Error 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. |
1004 | UNHANDLED_EXCEPTION | 500 | Unhandled exception occurred during the transaction. Please check the error description or report error logs for further investigation. |
1005 | PAN_NOT_PARTICIPATING | 400 | Primary Account Number (PAN) is not participating. Not returned in Auth API v2. |
1009 | MERCHANT_INTERFACE_DISABLED | 400 | The interface is disabled for this merchant. Not returned in Auth API v2. MERCHANT_ID_THREEDS_REQUESTOR_ID_INVALID (1026) will be returned instead. |
1011 | INVALID_LICENSE | 403 | Invalid ActiveServer license in use. Please resolve this licensing issue with GPayments as soon as possible. |
1013 | INVALID_TRANSACTION_ID | 400 | Transaction ID of 3DS Server is not recognised. This error code may be returned if threeDSServerTransID is invalid in the given request. |
1014 | INVALID_REQUESTOR_TRANSACTION_ID | 400 | Transaction ID of 3DS Requestor is not recognised. May be returned if the threeDSRequestorTransID is not in UUID format. |
1015 | THREEDS_REQUESTOR_NOT_FOUND | 400 | Invalid 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. |
1016 | MISSING_REQUIRED_ELEMENT | 400 | Required element missing. May be returned if required fields in the authentication API is missing. |
1018 | ELEMENT_NOT_DEFINED | 400 | Message element not a defined message. Not returned in Auth API v2. |
1019 | PROTOCOL_OLD | 500 | Protocol version is too old. Not returned in Auth API v2. |
1020 | ERROR_TRANSMISSION_DATA | 500 | Errors 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 (1001) . |
1021 | PRIOR_TRANS_ID_NOT_FOUND | 400 | Prior 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. |
1022 | INVALID_FORMAT | 400 | Format 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. |
1023 | CARD_RANGE_IS_NOT_VALID | 400 | Card range provided is invalid. Not returned in Auth API v2. |
1024 | CACHE_UPDATE_IS_DISABLE | 500 | Cache update is disabled. Not returned in Auth API v2. |
1025 | CACHE_REFRESH_INTERVAL_IS_NOT_SET | 500 | Cache refresh interval is not set. Not returned in Auth API v2. |
1026 | MERCHANT_ID_THREEDS_REQUESTOR_ ID_INVALID | 400 | Invalid 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. |
1027 | UNSUPPORTED_API_VERSION | 403 | This 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)¶
Code | Name | HTTP Status Code | Description | Auth API Description |
---|---|---|---|---|
2000 | NOT_FOUND | 404 | Resource not found. | Not returned in Auth API v2. |
2001 | DUPLICATE_RECORD | 409 | Record already exists. | Not returned in Auth API v2. |
2002 | VALIDATION_ERROR | 400 | Invalid inputs. | May be returned if the request is not properly formatted as a JSON. |
2003 | INVALID_REQUEST | 400 | Invalid request. | Not returned in Auth API v2. |
2004 | CONCURRENCY_FAILURE | 409 | Failed to update node. | Not returned in Auth API v2. |
2005 | ACCESS_DENIED | 401 | Access is denied. | Check the error detail for more description for why the access was denied. |
2006 | METHOD_NOT_SUPPORTED | 405 | Request HTTP method is not supported. | Not returned in Auth API v2 |
2007 | INTERNAL_SERVER_ERROR | 500 | Internal 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. |
2008 | DATA_INTEGRITY_VIOLATION_ERROR | 400 | A 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 |
2009 | SESSION_TIMED_OUT | 408 | Session has timed out. | May be returned if the transaction has already finished. |
Security Error Codes (3001 ~ 3024)¶
Code | Name | HTTP Status Code | Description |
---|---|---|---|
3001 | JDK_NOT_SUPPORT_SHA224WITHRSA | 500 | JDK used does not support the SHA224 with RSA algorithm. |
3002 | NO_SUCH_ALGORITHM | 500 | No such algorithm. |
3003 | INVALID_CERT | 400 | The certificate's public key is not compatible with the corresponding private key. |
3004 | INVALID_CHAIN | 400 | ActiveServer 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. |
3005 | NO_PRIVATE_KEY_FOUND | 400 | No private key found. |
3006 | INVALID_CERTIFICATE_CONTENT | 400 | Invalid certificate content |
3007 | CERTIFICATE_IO_READ | 400 | Unable to read certificate. |
3008 | SUCH_PROVIDER_EXCEPTION | 500 | No such provider exception. |
3009 | NO_KEY | 400 | The certificate could not be installed because this object does not have an existing key. |
3010 | CERTIFICATE_CHAIN_BAD_FORMAT | 400 | Certificate chain has invalid format. |
3011 | MISMATCHED_PASSWORDS | 400 | Password fields do not match. |
3012 | IMPORT_CERTIFICATE | 400 | No certificate found for the importing certificate. Please import client certificate. |
3013 | IMPORT_NO_CERTIFICATE | 400 | There is no certificate to export. |
3014 | FAILED_TO_INITIALIZE | 500 | Failed to initialise. |
3015 | ENCRYPTION_FAIL | 500 | Failed to encrypt. |
3016 | DECRYPTION_FAIL | 500 | Failed to decrypt. |
3017 | INVALID_HSM_PROVIDER | 500 | The specified provider name for hardware encryption is not supported |
3018 | INVALID_PKCS11_CONFIG | 500 | Invalid PKCS11 config path |
3019 | FAILED_TO_INITIALIZE_PKCS11 | 500 | Failed to initialise PKCS11. |
3020 | IMPORT_FAIL | 500 | Failed to import. |
3021 | NOT_SUPPORTED_IBM_PROVIDER | 500 | Only SUN provider is supported. |
3022 | UNABLE_TO_LOAD_KEYSTORE | 500 | Loading keystore failed. |
3023 | UNABLE_TO_LOAD_CERTIFICATE | 500 | Loading certificate failed. |
3024 | INVALID_KEY_SIZE | 500 | Key size is invalid. |
User Error Codes (4000 ~ 4022)¶
Code | Name | HTTP Status Code | Description |
---|---|---|---|
4000 | DUPLICATE_EMAIL | 400 | E-mail already in use. |
4001 | LAST_ADMIN_DELETE_NOT_ALLOWED | 400 | You need to be at least a System Admin user to perform this action. |
4002 | ACCOUNT_IS_LOCKED | 401 | Your account is locked. |
4003 | ACCOUNT_IS_DISABLED | 401 | Your account is disabled. |
4004 | ACCOUNT_WILL_BE_LOCKED | 401 | Your account will be locked after another wrong try. If you have been forgotten your password please click on "Lost your password" |
4005 | ACCOUNT_WAS_LOCKED | 401 | Password has been locked for 1 hour. |
4006 | ACCOUNT_IS_INACTIVE | 401 | Your account was not activated. |
4007 | PASSWORD_POLICY_MATCH | 401 | The password should be minimum eight characters, with at least one letter and one number. |
4008 | LOGIN_ALREADY_IN_USE | 401 | Username already in use. |
4009 | EMAIL_ALREADY_IN_USE | 401 | Email already in use. |
4010 | INVALID_TOTP_CODE | 400 | Invalid totp authentication code. |
4011 | EMAIL_SENDING_FAILED | 400 | Failed to send email. |
4012 | EMAIL_NOT_REGISTERED | 400 | Your email is not registered. |
4014 | FAILED_TO_CREATE_ACCOUNT | 500 | Failed to create the account. |
4015 | TWO_FA_MANDATORY | 400 | Using two factor login is mandatory. |
4016 | PASSWORD_EXPIRED | 403 | The password for user was expired. |
4017 | PASSWORD_EXPIRED_WARNING | 403 | The password for user is going to be expired on. |
4018 | PASSWORD_HISTORY_MATCHED | 403 | The password matched with the previous historical passwords. |
4019 | INVALID_TOKEN | 400 | An invalid token. |
4020 | INVALID_HSM_PIN | 400 | Invalid HSM Pin. |
4021 | INVALID_PASSWORD | 400 | Invalid password. |
4022 | EMAIL_INVALID_ACTIVATION | 403 | Account activation code is invalid. |
Setup Error Code (5000)¶
Code | Name | HTTP Status Code | Description |
---|---|---|---|
5000 | SETUP_NOT_ALLOWED | 500 | Setup is not allowed. |