Error codes
This section provides details of errors that could occur during the running of ActiveServer.
Authentication API Error Codes Overview¶
- Only error codes in category 3DS Error Codes, Transaction Error Codes and General Error Codes can be returned from the Authentication API(
/api/v2/auth/**
). - Security Error Codes, User Error Codes or Setup Error Code will not be returned during the Authentication API.
- For each error codes, associated HTTP status code from the table below will be returned.
- Error code description contains the possible scenario in which the error code may be returned, and for some error codes common solutions are also highlighted.
Description of each error code categories are as below:
3DS Error Codes - Error codes in this category is defined by the EMVCO Core Protocol specifications. Error codes defined here can be returned from either 3DS Server (ActiveServer), DS, ACS or the 3DS SDK. The component in which identified the error will return the error response and set the
errorComponent
field as itself in the JSON response (e.g. if error was identified by DS it will set theerrorComponent
toD
). If the error was identified in components that is outside of ActiveServer, ActiveServer will return the same error JSON back to the 3DS Requestor.errorMessageType
,errorDetail
anderrorDescription
field can be used to interpret the message that was erroneous. Please refer to theApiErrorResponse
model for description of each fields.Transaction Error Codes - Transaction error code defined by ActiveServer.
errorComponent
field will beS
at all times because the error was identified by 3DS Server.General Code - Errors that does not fall into either 3DS Error Codes or Transaction Error Codes are returned as General Code. The error code may be returned also from the Admin API. Check the Auth API Description for descriptions related to the Authentication API.
Tip
Please note that error codes which has the tag Not returned in Auth API V2 will not be returned as a response for
/api/v2/auth/**
.
3DS Error Codes (101 ~ 405)¶
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. e.g. 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. e.g. 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. e.g. acsReferenceNumber sent from ACS to DS is invalid. |
304 | ISO_CODE_INVALID | 400 | ISO code not valid per 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 e.g. send 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. |
Transaction Error Codes (1000 ~ 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. If error occurred while saving raw message e.g. saving raw AReq JSON, 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 | ActiveServer is running on invalid license. Please resolve licensing issue with GPayments. |
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/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 error with sending request and receiving 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 | Error in setting requestor prior Transaction ID. Prior Transaction ID couldn't be found. It will be returned if priorTransID given in the authentication request is not valid. |
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. e.g. 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 auth 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 ~ 2010)¶
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. e.g. 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. |