Home > Codes


Error Codes



Overview  
In cases when a system error occurs, the gateway returns an exception. As a transaction, for which an exception is received, does not go through the gateway's validation, it's not submitted to a processor either. For this reason, such transactions can be stored neither within the database nor in the list of transactions. Every exception consists of the following elements:

1. failureCode - a unique identifier of an exception. Includes an identifier and number of an error. The following error categories are available within the system:
  • L - login/security error. Occurs when a login attempt is unsuccessful or a user misses one or more privileges to be able to use API;
  • F – formatting error. Occurs when data provided by a submitter does not adhere to the formatting requirements. For example, a submitted value for phone field contains letters or a submitted value for amount field is negative;
  • V – data verification error. Occurs when data provided by a submitter is well-formatted, but one or more values are not valid from the business context. For example, referenced merchant account does not exist or a specified transaction industry type has not been found within a list of the allowed values;
  • O – configuration error. Occurs when data provided by a submitter is well-formatted and valid, but specific settings required for a transaction to be processed are not configured correctly. For example, there are no pricing templates configured within specified portfolio while a merchant that is being created cannot be onboarded without these settings;
  • U – unsupported action error. Occurs when data has been validated successfully and all required settings are configured, but specified operation/feature is not supported either by the gateway or a processor. For example, operation is not supported by an underlying processor or cashback is not supported for sale-info or credit-info operations;
  • S – system error. An internal system error occurred. Gateway support should be reached out;
  • Q – security error. Occurs when there is a possibility of a security breach or missed encoding.

2. failureMessage - consists of the details of an exception that specify the reason why the transaction cannot be processed. The structure of the failure message looks as follows:
  • User message - a message describing what caused the error, for example, zipCode is not well-formatted.
  • Developer message - a message containing a list of dynamic parameters included in the user message'. Using these parameters, you can override user messages with your own custom error messages. See Processing Management Guide for more information.
  • Hint - a number, which refers to the additional information about an error, for example, Hint:1. If a hint is returned as a part of the failure message, you should refer to the description of the corresponding error in the section below.
If needed, the structure of error messages can be modified at the service user level via the Response Msg Display Policy setting by removing or adding any of the options described above.

These exceptions are currently used within the gateway. In the previous versions of the application, as well as in the older logic, deprecated exceptions can still be present. Follow the link to see the overview of the exceptions deprecated within the system.

Configuration Error Codes  
Code User Message Developer Message Description
O21 ConfigurationName is not configured for the referenced ReferenceName.
object: ConfigurationName, reference: ReferenceName
A particular configuration, required to complete the action, is not set up within the gateway for the referenced entity. If you have access to the indicated configuration, you can set it up, otherwise, reach out to the gateway support to have these settings configured. For example, you are attempting to process a real-time transaction, however, a processor for the merchant you using is not configured.
O22 The selected action is not allowed by ReferenceName settings.
reference: ReferenceName
A particular action cannot be completed because associated referenced entity is configured to not allow the action. If you have access to the settings of the indicated reference entity, you can modify them to be able to complete the action, otherwise, reach out to the gateway support to have these settings modified. For example, you are attempting to send an email to the customer which settings do not allow email sending.

Hint 1: A provider profile uses host capture, which is incompatible with manual settlement type. Change the settlement type within the merchant processing settings or select a provider that uses terminal capture instead.
O24 SettingName is not configured for the referenced ReferenceName.
object: SettingName, reference: ReferenceName
A particular setting, necessary to complete the action, is not set up within the gateway for the referenced entity. If you have access to the indicated setting, you can set it up, otherwise, reach out to the gateway support to have these settings configured. For example, you are attempting to reset your password, however, an email in your user profile is not set.
Formatting Error Codes  
Code User Message Developer Message Description
F21 FieldName is missing.
field: FieldName
Value of the field, which is required, was not supplied. Make sure that you are supplying the value for the indicated field.

Hint 1: One of the conditionally required values was not supplied. Verify the usage for field values you are supplying and try again.
F22 FieldName is not well-formatted.
field: FieldName, value: FieldValue
Value of the field, which requires specific formatting, does not adhere to the formatting requirements. Verify what are the formatting requirements for this field and make sure you follow them.

Hint 1: Password must be different from the current or previous three passwords, as well as must contain at least one digit, one lowercase and one uppercase character.
F23 FieldName length must be LengthNumber characters.
field: FieldName, limit: LengthNumber, value: FieldValue
Value of the field, which has a fixed length, is shorter or longer than the required length. Verify what is the required length of the field and make sure that the value you are supplying has this specific length.
F24 FieldName length must be between LengthFrom and LengthTo characters.
field: FieldName, from: LengthFrom, to: LengthTo, value: FieldValue
Value of the field, which length has to be in a specific range, is out of range. Verify what is the required length range and make sure that the value you are supplying falls into this range.
F25 FieldName must be within range from RangeFrom to RangeTo.
field: FieldName, from: RangeFrom, to: RangeTo, value: FieldValue
Value of the field, which is required to be in a specific range, is out of range. Verify what is the required value range and make sure that the value you are supplying falls into this range.
F26 FieldName length must be RelationName LengthNumber characters.
field: FieldName, relation: RelationName, limit: LengthNumber, value: FieldValue
Value of the field, which is required to have a particular length, does not correspond to the requirements. Verify what is the required length range and make sure that the value you are supplying falls into this range.
F27 FieldName must be RelationName RangeNumber.
field: FieldName, relation: RelationName, limit: RangeNumber, value: FieldValue
Value of the field, which is required to be in a particular range, does not correspond to the requirements. Verify what is the required value range and make sure that the value you are supplying falls into this range.

Hint 1: For sole proprietorship, stake percentage of the officer must equal 100%. For all private ownership structure types (except government agency and tax-exempt organization) stake percentage of the officer must be greater than 0%.
F28 FieldName must contain at most SubrecordNumber subrecords. Invalid value: FieldValue.
field: FieldName, limit: SubrecordNumber, value: FieldValue
Value of the field, which has a List type, exceeds an allowable number of subrecords. Verify what is the maximum number of subrecords and make sure that the value you are supplying does not exceed this number.
F29 The total of FieldName fields of ReferenceName records must be within a range from RangeFrom to RangeTo.
field: FieldName, reference: ReferenceName, from: RangeFrom, to: RangeTo, value: FieldValue
Values of the fields, the total of which is required to be in a specific range, is out of range. Verify what is the required value range and make sure that the values you are supplying fall into this range.
Login Error Codes  
Code User Message Developer Message Description
L01 Username or password is invalid.
Username or/and password you supplied is invalid. Make sure that the value you are supplying is correct.

Hint 1: Indicated user can log in to the application using a temporary password only. Generate a temporary password via authentication API call and try again.

Hint 2: A terminal has sent malformatted credentials. Verify what are the requirements for username and/or password for the selected terminal mode and make sure you follow them.
L02 Only one authentication session per human user is allowed.
You have already been logged in with these credentials within another user session (another machine or browser is currently in use). Verify that authentication session is expired (15 minutes), and try to log in again.
L03 Referenced account is locked due to LockReason. Contact support.
object: LockReason
Your account has been locked due to an extended period of inactivity or password expiration. Please contact support.
L04 Processing of raw account data is not allowed through the specified API end-point.
The submitted request contains sensitive data and cannot be processed through the specified end-point by an indicated user. Make sure that a corresponding setting is enabled for the user.
L05 User UserName is missing PrivilegeName privilege.
user: UserName, object: PrivilegeName
A particular action cannot be completed because the service user does not have a respective privilege. Make sure that a corresponding privilege is enabled for the user.
L06 User UserName is missing PermissionName permission.
user: UserName, object: PermissionName
A particular action cannot be completed because the human or system user does not have a respective permission. Verify a list of available permissions and make sure that the action you are attempting to perform is allowed.
L07 User session expired due to inactivity or session timeout limit.
User session or temporary password has expired. Make sure the values you are supplying as credentials are valid and try to log in to the application again.
L08 One time password is invalid.
One-time password you supplied is invalid. Make sure that the value you are supplying is correct.
L09 Processing of RequestType is not allowed through the specified API end-point.
operation: RequestType
The submitted request is disabled at the system level and cannot be processed through the specified end-point. Make sure that a corresponding setting is enabled.
Security Error Codes  
Code User Message Developer Message Description
Q01 XSS injection detected.
The request cannot be completed due to the possible XSS injection.
Q02 The request is not properly encoded.
One or more values you are supplying are not URL-encoded. Verify that all values within the request are encoded.
System Error Codes  
Code User Message Developer Message Description
S20 OriginName error. Contact support.
object: OriginName
An error that cannot be resolved by the user has occurred within the system. Please contact support for further investigation.
For example, there is an issue with the database and it is not available at the moment.

Hint 1: There is an application deployment integrity issue. Possibly you are missing some of the required libraries or some of the JAR files are damaged or not properly built. Contact gateway support or verify whether the application was deployed correctly.

Hint 2: There is a possible settlement issue with the processor that you currently use. Contact gateway support for assistance.

Hint 3: Number of parallel connections in a processor's system is out of limit, and some transactions submitted by the gateway cannot be processed at the moment. To resolve the issue, either increase a transaction timeout in the gateway or reach out to the processor to allow more connections on its side.
S21 We are experiencing temporary issues with the processor. Contact support.
An unexpected error occurred on a processor's side. You can contact support to initiate further investigation.
For example, the processor's servers are down at the moment.
S23 We are experiencing temporary connectivity issues. Contact support. ConnectivityErrorName
There is an issue with the connection between the gateway and either a processor or a particular gateway module. Please contact support for further investigation.
For example, terminal cloud is unavailable at the moment due to an internal error.
S24 Data you are trying to use is corrupted. Contact support.
Particular data cannot be read and/or processed by the system because of an invalid format. Please contact support for further investigation.

Note: The error code is now deprecated. Starting with the 7.1 release, the error is replaced with S34.
S24 Payment page configuration issue. Contact support.
An error has occurred due to the incorrect payment page configuration. Please contact support for further investigation.
For example, responseMessageDisplayPolicy setting has been set as (-D-), i.e. only developer messages have been selected to be shown on the payment pages, and one or more errors were not overridden by the getUserMessage function. See Processing Management guide for more information.

Note: The error code is available starting with the 7.1 release.
S25 ProcessName process failed. Contact support.
object: ProcessName
An internal error occurred during the indicated process. Please contact support for further investigation.
For example, encryption process cannot be completed due to a missing encryption key.
S26 Operation RequestType declined by the processor.
An operation has been declined by a processor. Applied to void and capture operations only.
S27 No Internet connection detected.
Internet connection is disabled on a device. Make sure you have enabled Internet on the mobile device.
S28 Unable to submit FormatName to ProfileType. Daily limit of FormatNames is reached.
object: FormatName, object: ProfileType
A file/transaction cannot be processed by a processor due to the daily limit of files/transactions submission being exceeded. Please try again tomorrow.
S29 No data is available for the specified criteria.
An operation cannot be performed for the parameters indicated in the request. Try to submit different criteria.
For example, a report cannot be generated for the criteria specified in the request.
S32 Referenced ReferenceName is not found within the system. Contact support.
reference: ReferenceName
The referenced entity does not exist within the system. Please contact support for further investigation.
For example, a batch response file is sent from a processor to the gateway, but the corresponding request file cannot be found within the system.
S33 Data cannot be extracted from the archive. Verify integrity of the file.
The submitted archive cannot be read or unzipped. Make sure you are submitting a file in proper format.
S34 Invalid FormatName format detected. Contact support. 
object: FormatName
A particular file or data cannot be read and/or processed by the system because of an invalid format. Please contact support for further investigation.
For example, the system downloads an aggregated file from a processor but due to the invalid format, the file cannot be divided in several files and processed correctly.

Hint 1: Your SQL request is invalid and cannot be processed. Verify that a query you are trying to execute is among a list of queries that are allowed to be used within the DQM module. See the following document for more information about the queries that are prohibited to run.

Hint 2: An archive with terminal tasks, which a user attempts to upload to the repository, has an invalid structure: the name of the second-level directory within the archive does not correspond to the value of a terminal task enumeration. Contact gateway support for assistance or try to upload a different archive.

Hint 3: Buffer overflow error: data sent from the server/POS to a terminal is too large.

Hint 4: The file you are attempting to submit is too large.
S35 Data encoding issue detected. Contact support.
A particular file or data cannot be processed due to an internal encoding error. Please contact support for further investigation.
For example, an aggregated file downloaded from a processor's FTP cannot be parsed correctly.
S36 MethodName is not supported.
object: MethodName
The method you are attempting to use is not supported for the submitted API request. Verify what methods are available for the request you are attempting to submit and make sure that the method you are using is allowed.
For example, you are attempting to use GET method, which is not supported for processing real-time API requests.
S38 Maximum number of ReferenceNames is reached at the LevelName level.
reference: ReferenceName, level: LevelName
The indicated entity cannot be created due to the limit of the entities of this kind being exceeded. For example, you are attempting to create an account #1000 under a merchant that already has 999 accounts, which is a maximum number of the accounts that the merchant can have.

Hint 1: A maximum number of pre-allocated Discover MIDs is reached. Contact gateway support for assistance.
S99 Internal error.
An internal error occurred. Please contact support for further investigation.
Unsupported Error Codes  
Code User Message Developer Message Description
U22 FeatureName feature is not supported for the RequestType operation.
feature: FeatureName, operation: RequestType
The feature you are attempting to execute is not supported for the submitted operation. Verify what features are available for the indicated requestType and make sure that the feature you are submitting is allowed.
For example, you are attempting to make cashback, which is not supported for sale-info transactions.
U23 FeatureName feature is not supported by the processor configured.
feature: FeatureName
The feature you are attempting to execute is not supported by a processor. Verify what features are available for the processor configured for your account and make sure that the feature you are submitting is allowed.
For example, you are attempting to execute pre-tokenization, which is not supported by FirstData Nashville.
U24 FeatureName feature is not supported for AccountTypeName transaction.
feature: FeatureName, accountType: AccountTypeName
The feature you are attempting to execute is not supported for an indicated payment card or account. Verify what features are available for the indicated payment option and make sure that the feature you are submitting is allowed.
U25 RequestType operation is not supported for TransactionType transactions.
operation: RequestType, object: TransactionType
The operation you are attempting to execute is not supported for a type of the transaction that you are referencing. Verify the type of the transaction using transactionId/transactionCode and make sure that the operation you are submitting is allowed.
For example, you are attempting to execute capture, which is not supported for sale transactions.
U26 FeatureName feature is not supported for the specified transaction.
feature: FeatureName
The feature you are attempting to execute is not supported for the referenced transaction. Verify the type of the transaction using transactionId/transactionCode and make sure that the feature you are submitting is allowed.
For example, you are attempting to execute partial capture for the transaction that was split.
U27 RequestType operation is not supported by the processor configured.
operation: RequestType
The operation you are attempting to execute is not supported by a processor. Verify what operations are available for the processor configured for your account and make sure that the operation you are submitting is allowed.
For example, you are attempting to execute credit-auth, which is not supported by the processor configured.

Hint 1: A processor does not support the specified operation for merchants of the specified country.
U28 ActionName operation is not supported for the referenced ReferenceName.
operation: ActionName, reference: ReferenceName
A particular action cannot be completed for the entity you are referencing. Verify a list of actions available for the reference entity and make sure that the action you are using is allowed.
For example, you are attempting to create flat merchant fees that cannot be created/modified by the affiliate merchants.
U29 RequestType operation is not supported for AccountTypeName transaction.
operation: RequestType, accountType: AccountTypeName
The operation you are attempting to execute is not supported for a type of the indicated payment card or account. Verify what operations are available for the indicated payment option and make sure that the operation you are submitting is allowed.
For example, you are attempting to execute refund, which is not supported for debit cards.
U30 AccountTypeName processing is not supported.
accountType: AccountTypeName
The type of a payment card or account that you are attempting to use is not supported for the referenced transaction type. Verify what card/account types are supported for the operation you are trying to execute and make sure that the type you are using is allowed.
For example, you are using a fleet card, which is not supported for recurring billing transactions.
U31 RequestType operation is not supported for ProcessingMode transactions.
operation: RequestType, object: ProcessingMode
The operation you are attempting to execute is not supported with the submitted processing mode. Verify what operations are available for the indicated processing mode and make sure that the operation you are submitting is allowed.
For example, you are attempting to execute the convenience-fee operation, which is not supported for transactions with processingMode=queue.
U32 RequestType operation is not supported for TransactionIndustryType transactions.
operation: RequestType, object: TransactionIndustryType
The operation you are attempting to execute is not supported for the submitted transaction industry type. Verify what operations are available for the indicated transaction industry type and make sure that the operation you are submitting is allowed.
For example, you are attempting to execute the increment operation, which is not supported for transactions with transactionIndustryType=C21.
Validation Error Codes  
Code User Message Developer Message Description
V21 FieldName is invalid.
field: FieldName, value: FieldValue
The supplied value, while being properly formatted, is actually invalid. Verify what value verification procedures are done and make sure that the value you are supplying satisfies these verification procedures. For example, if you are submitting a routing number, which is subsequently validated against a specific list, make sure that the value that you supplied is validated against that list as well.

Hint 1: Both conditionally required and conditionally not used field values were supplied. Verify the usage for field values you are supplying and try again.

Hint 2: An invalid report name was supplied. Verify what reports are available within the Reporting API specification and make sure you are supplying a correct value.

Hint 4: The root, admin and administrator values cannot be indicated as a user's name. Enter another value and try again.
V22 FieldName is not among allowed values.
field: FieldName, value: FieldValue
The supplied value has not been found within the list of allowed values for the indicated field. Verify what values are available within the list and make sure that the value you are supplying is allowed.

Hint 1: An invalid content type was supplied. Verify what types are available for the selected report within the Reporting API specification and make sure you are supplying a correct value (PDF, CSV or data).

Hint 2: A list of the values allowed for a field may be limited by the value of another field. For example, a list of ownership structure types differs from country to country.
V23 Field FieldName is required because more than one ReferenceName is available to the user.
field: FieldName, reference: ReferenceName
Reference entity, which is required to be submitted since the user has access to two or more reference entities, was not supplied. Make sure that you are supplying the value for the indicated reference entity. For example, if you are submitting onboarding API request while having access to two portfolios, make sure that portfolio ID is supplied.
V24 Referenced ReferenceName is not found within the LevelName or not accessible to the current user.
reference: ReferenceName, level: LevelName, value: FieldValue
The referenced entity is not accessible to your user account or does not exist within the specified scope: it is possible that there is no such reseller at all, or it exists under a different portfolio. Verify that you are referencing to an existing entity and have proper access to the entity you are referencing. For example, you are referencing the reseller, however, there is no such reseller within the portfolio you have access to.
V26 Referenced ReferenceName is not active.
reference: ReferenceName, value: FieldValue
The referenced entity is not active and cannot be used. Verify that the entity you are referencing is active within the system. For example, you are referencing a merchant that is no longer active.
V27 Merchant profile settings do not allow ReferenceName creation.
reference: ReferenceName
The entity that you trying to create cannot be set up under the referenced merchant because of merchant profile settings. Verify that merchant profile settings reflect business needs of that merchant. See Merchant Configuration guide for more information.
V28 AmountName must be RelationName AmountName.
field: AmountName, relation: RelationName, relatedField: AmountName, value: FieldValue
The supplied amount value is less or greater than the amount associated with the transaction. Verify the original transaction amount and make sure you do not go beyond the minimum/maximum amount value.
For example, the amount value you are supplying within the void API request is greater than an authorization amount of the original transaction.
V29 The transaction you are trying to process is a duplicate of a recently processed transaction.
The submitted transaction is a duplicate of a transaction you have submitted earlier. Make sure the transactionCode and accountId values of the transaction you are submitting and previously processed transaction do not match.
V31 Cannot complete ActionName action. Referenced ReferenceName is in use.
operation: ActionName, reference: ReferenceName, value: FieldValue
A particular action cannot be completed for the entity you are referencing because active references to the entity exist within the system. Make sure that referenced entity is not in use.
For example, you are attempting to delete a provider profile through which transactions are being processed.
V32 ObjectName is already StateName.
reference: ObjectName, object: StateName
The submitted transaction or ticket cannot be processed due to the incorrect current state. Verify the status of the transaction you are trying to process.
For example, you are attempting to void/capture a transaction that has already been voided/captured.
V33 FieldName is a FieldType field.
field: FieldName, object: FieldType
The supplied field is either read-only or create-only and cannot be modified. Verify the type of the field you are trying to submit.
V35 Identifier of the referenced ReferenceName is not unique.
reference: ReferenceName, value: FieldValue
One or more reference entities with the specified identifier exist within a level you can access. Make sure you are supplying a unique value for the entity identifier.
V37 Account ID specified at the splits field level must be different from account ID specified at the transaction level.
The same values of the accountId fields have been submitted at the splits field and the transaction level. Make sure you are supplying the different values for these fields.
V38 Split rules can be submitted at either the items field level or the transaction level.
Split rules have been submitted via two fields in the transaction - the items field and the splitSchemaId/splits fields. Make sure you are supplying split rules via only one of these fields.
V39 Split rules can be submitted via either the splits field or the splitSchemaId field.
Split rules have been submitted via two fields in the transaction - the splitSchemaId field and the splits field. Make sure you are supplying split rules via only one of these fields.