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 code	Nexio error code	Description	Proposed solution
400	408	Payment gateway timeout	There 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.
400	409	This `merchantId` is not enabled for payment processing. Please check your request or contact Integrations Support.	Go to the Dashboard and verify that the indicated`merchantId` 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.
400	418	Unsupported 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.
400	418	Due 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.
400	419	No `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.
400	431	Kount 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.
400	431	Kount risk identified.	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	432	Invalid currency	Contact Integrations Support to verify that the currency specified in the request is configured for the payment method used.
400	433	Invalid gateway	Contact Integrations Support to verify that the gateway or connection has been configured for the merchant account.
400	434	Invalid TokenEx configuration.	There is a problem with the TokenEx configuration. Contact Integrations Support for assistance with fixing this issue.
400	434	TokenEx 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.
400	434	Tokenization 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.
400	435	Unable to process with gateway.	For more information about the possible reasons and solutions, see the Handling gateway declines topic.
400	436	Missing 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.
400	436	Missing required fields	The error message details include the names of the required fields that are missing. Add any missing parameters and appropriate values and retry the request.
400	436	Unable to capture void or refund	Indicates 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".
400	437	Failed card security code check	For more information about how to work with security code errors, see Handling security code verification failures topic.
400	438	This 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.
400	441	Amount value is not a number	This 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.
400	443	Verify AVS Failed	There 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.
400	446	Authentication Failed	Indicates an issue with the configuration of 3DS on the merchant account. For assistance with this, contact Integrations Support . You can also see the Using 3DS to run transactions tutorial for additional troubleshooting help.
401	440	Insufficient access	The 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.
401	440	Card merchant is not associated with requesting account	For 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.
404	404	The requested item is not found	Refer 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.
404	404	Merchant not found or invalid merchant configuration	Confirm 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.
409	409	Either 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.
500	439	Unable to load TokenEx	There was a problem with TokenEx. Retry the request. If the error continues, contact Integrations Support.
500	5xx	Generic server error	There was a problem with the connection to Nexio. Retry the request. If the problem persists, contact Integrations Support.
500	505	An internal process failed. There was an error validating the schema.	For help with this error, contact Integrations Support.

Common errors

Error code table

See also