Common errors

The following are common errors that you might receive.

Please contact us if you want to discuss or get assistance with error messages.

The error codes can have multiple causes depending on the specific type. From a hierarchical perspective, think of them in a progression from HTTP status > Nexio Status > Description. So, for example, with the two rows for HTTP 404 (4xx series error, specifically 404 Not found) and Nexio 404 error (Not Found), there can be multiple possible reasons for not found. This is why there are two rows listed - generic not found and merchant not found - depending on the specific cause for the error. Therefore, make sure to always reference the description when working with errors.

Error code table

HTTP status codeNexio error codeDescriptionProposed solution
400408Payment gateway timeoutThere was an error with the gateway. Before proceeding, verify that the transactions did not actually succeed on the gateway or connection level by querying the View transactions endpoint (filtering, for example, by transactionDate).

If the transaction did not succeed, attempt the request again. If the problem continues, contact Integrations Support.
400409This merchantId is not enabled for payment processing. Please check your request or contact Integrations Support.Go to the Dashboard and verify that the indicatedmerchantId is associated with the API user,. Also, verify that if you are passing a merchantId, that it is a valid value.

After checking those, if you are still getting this error, contact Integrations Support for further assistance.
400418Unsupported action or browser, or device does not support Apple Pay.For Apple Pay, you must test using a product such as Safari web browser or a device such as an iPad that supports Apple Pay.
400418Due to government sanctions we are unable to process the RUB currency. Please check your request or contact integration support.The current solution for this issue is to change to process with a different currency.
400419No recurringId with the attempted gateway on the card token provided. You may need to send a different paymentType or include the CVV.This means that a recurring paymentType was sent on an initial transaction.

Send a different payment type or include a security code for a recurring transaction.
400431Kount credentials were invalid. Please check your request or contact integration support.This error indicates that the Kount credentials were encrypted incorrectly or that they are not correct credentials. Contact Integrations Support to fix this issue.
400431Kount has identified a possible risk with the transaction.Indicates that Kount identified a risk. For information about test values to trigger failures, see the Testing Kount verification topic. To learn about the aspects of the Kount response, see the Understanding the Kount response topic.
400.432Invalid currencyContact Integrations Support to verify that the currency specified in the request is configured for the payment method used.
400433Invalid gatewayContact Integrations Support to verify that the gateway or connection has been configured for the merchant account.
400434Invalid TokenEx configuration.There is a problem with the TokenEx configuration. Contact Integrations Support for assistance with fixing this issue.
400434TokenEx credentials were invalid. Please check your request or contact integration support. This error indicates that the TokenEx credentials were encrypted incorrectly or that they are not correct credentials. Contact Integrations Support to fix this issue.
400434Tokenization error, failed to process token: [tokenex.token], please contact Support.Contact Integrations Support with any additional error message information for help with fixing this issue.
400435Unable to process with gateway.For more information about the possible reasons and solutions, see the Handling gateway declines topic.
400436Missing one time use token in GET query sting.The one-time-use token is missing from the query string in your request. Add a valid one-time-use token to the query string.

For information about getting a token, see the Create one-time-use token endpoint.
400436Missing required fieldsThe error message details include the names of the required fields that are missing. Add any missing parameters and appropriate values and retry the request.
400436Unable to capture void or refundIndicates that the transaction is not in a state that allows for the attempted action. For example, you can only refund transactions that have a status of "settled".
400437Failed card security code checkFor more information about how to work with security code errors, see Handling security code verification failures topic.
400438This request is invalid due to the amount field. Please check your request.Check the amount field to make sure it is a valid number, non-negative, and uses any punctuation such as commas correctly.
400441Amount value is not a numberThis means that the value passed in the amount parameter is not a number or cannot be converted to a number. Check your request and try again.
400443Verify AVS FailedThere was a failure in the Address Verification Service (AVS). For information about test values to trigger responses, see the Testing AVS topic. For information about the response, see the Understanding the AVS response topic.
401440Insufficient accessThe API user does not have appropriate access rights to perform this action. Either use a user with more access rights or give the current user those rights. For more information, see the User roles topic.
401440Card merchant is not associated with requesting accountFor the View surcharge recommendation endpoint, this means that either surcharging is not enabled on the account or that the specific card brand is not enabled for surcharging. First, attempt to log in to the Dashboard with an admin-level user and verify that no new agreement needs to be signed. Then, for enabling surcharging or specific cards, contact Integrations Support.
404404The requested item is not foundRefer to the specific error message for information about how to fix this. Make sure that the item (such as the transaction, token, payment, chargeback, payout, and so forth) is valid and that you are passing it correctly. Verify that the API user has access to the merchant account for the indicated item.
404404Merchant not found or invalid merchant configurationConfirm that the merchantId you are passing is assigned to the API user you are using to make the request.

Use the Who am I endpoint to verify the configuration.
409409Either the routing rules (Dashboard Payment Routing or paymentOptionTag) filtered out all possible merchants or the filtered merchants do not have this paymentMethod and currency combination configured. Please check your request, edit your Payment Routing rules in the Nexio Dashboard Settings, or contact Integrations Support.First, go to the Dashboard and check for any routing rules. If there are rules, verify that the rules do not filter out all payment options for the merchant account.

Next, verify that you are using a valid paymentOptionTag, that the tag has a valid payment method and currency associated with it, and that the transaction being sent does not override that currency or payment method with an unsupported value.

For additional assistance, contact Integrations Support.
500439Unable to load TokenExThere was a problem with TokenEx. Retry the request. If the error continues, contact Integrations Support.
5005xxGeneric server errorThere was a problem with the connection to Nexio. Retry the request. If the problem persists, contact Integrations Support.
500505An internal process failed. There was an error validating the schema.For help with this error, contact Integrations Support.

See also