Error codes in recurring charges

September 16, 2024

Learn how to manage different types of error messages received during transactions for each payment method.

What types of response codes does Kushki return?

Kushki will return two different response codes to indicate the success or failure of a transaction: processorError and code. The code field returns generic messages. On the other side, the field processorError indicates that the transaction has passed through the processor and has probably been mapped by Kushki in order to provide a specific explanation of the reason why your transaction could not be completed.

Codes returned by Kushki for recurring card charges

Kushki’s API will perform validations before sending a transaction to the processors. If this is the case, the processorError field will not appear in the response and you will only see the code field. An example of a message returned by Kushki’s API is shown below:

    {"message": "Comercio deshabilitado",
    "code": "K026" }

In the table below, generic error codes returned through the code field are summarized.

code	message	What to do?
K001	Invalid request body	Check request body
K003	Error in gateway response	Retry, in case the error persists, contact Kushki’s support team, so we can review your case
K004	Invalid merchant ID	Check public merchant ID or private merchant ID and retry
K006	Subscription rejected due to collection validation	Retry transaction
K007	Card blocked by the issuer	Try another card
K008	Incorrect token	Fill in the data again and retry
K010	Merchant not eligible for subscriptions	Contact Kushki’s support team, so we can review your case
K011	Invalid start date	Check the start date submitted in the `startDate` variable
K012	Invalid subscription ID	Check amount to capture and retry
K013	Invalid end date	Check the date submitted in the `endDate` variable
K014	Invalid capture amount	Check amount to capture and retry
K015	Transaction not allowed without CCV2	Check CVV and retry
K016	Unable to update subscription	Check information submitted and retry
K020	ERROR_REJECTED_TRANSACTION	Retry the transaction; in case the error persists, contact Kushki’s support team, so we can review your case
K021	Subscription refused by SiftScience	Retry the transaction as it may be due to an error in the connection with the anti-fraud validation provider
K022	Subscription refused due to a previously used token	Request a new token and retry the transaction
K023	Void amount higher than sale	This message is displayed when trying to make a partial void, but the amount is higher than the sale amount
K024	Amount value must be greater than zero	Check amount submitted and retry
K025	Invalid card	Try another card
K026	Merchant disabled	Contact Kushki’s support team, so we can review your case
K027	Unable to complete transaction	Retry transaction
K028	Processor Declined	Contact Kushki’s support team, so we can review your case
K029	Card details do not match in the subscription and its confirmation	Check the details submitted and retry
K031	No webpay subscription to confirm	Check the subscription ID submitted and retry
K032	The webpay subscription has been previously confirmed	-
K034	No processors exist	Contact Kushki’s support team, so we can review your case
K035	Processor not available	Retry. If the error persists, contact Kushki’s support team, so we can review your case
K036	Third party integration error	Contact Kushki’s support team, so we can review your case
K037	Subscription not found	Check the subscription ID submitted and try again
K038	Partial void cannot be performed without specifying the value to be deducted	Specify the `amount` object
K039	The sum of the values of the amount property must be greater than 0	An amount greater than 0 must be submitted in the amount property.
K040	The merchant ID does not match the credential submitted	An amount greater than 0 must be submitted in the amount property.
K041	Transaction not allowed	Contact Kushki’s support team, so we can review your case
K042	The currency code is different from that of the initial transaction.	This message is displayed when a currency code other than that of the initial transaction is submitted. Submit the correct currency code.
K043	Preauthorization transaction does not match subscription	Check submitted information and try again
K044	The entered BIN does not support this payment method	Try another card
K045	Capture transaction previously performed	Capture cannot be performed again
K046	The transaction went into timeout, please try again	Retry the transaction
K047	An unexpected error has occurred	Retry the transaction
K048	Processor does not support the current method	Contact Kushki’s support team, so we can review your case
K049	Card expired	Try another card
K050	This token is no longer valid	Check the data submitted and retry
K051	The merchant does not have the deferred option enabled	Contact Kushki’s support team, so we can review your case
K052	ERROR_REJECTED_TRANSACTION	Retry the transaction; in case the error persists, contact Kushki’s support team, so we can review your case
K027	The transaction went into timeout, please try again	Retry the transaction

Error codes when transaction goes to the processor

Below we describe error codes returned through the processorError field, so that you can use them to map your application messages.

In the processorError and message columns of the table, the error code and message sent by Kushki are shown. In the column What to do?, we provide you with a more detailed explanation of the causes and the possible procedure to follow.

processorError	message	What to do?
501	Rejected transaction. Contact your card issuer	The cardholder must contact his/her card issuer to understand why the transaction was rejected
503	The business number is not registered	The endpoint number or business code is not registered or enabled in the payment processor. Contact Kushki’s support team so we can review your case.
504	The card entered has been reported.	The cardholder must use a different card to process the transaction and contact their card issuer for them to review the case.
505	The transaction was declined by the processor or issuer.	The cardholder must wait a couple of minutes and retry; otherwise, their must use an alternative card.
512	Transaction not allowed by the issuer.	The transaction is not allowed by the payment processor or the card issuer. The cardholder should use an alternative card.
513	The amount entered contains an invalid syntax	It is necessary to verify the amount entered and retry. For example, it is possible that unallowed characters have been entered in the amount field, as `,` instead of `.` to separate decimals.
514	The card number entered is not valid	The cardholder must verify that the card number has been entered correctly and retry.
515	The card issuer cannot authorize this transaction	The payment processor or card network rejected the submitted BIN. The cardholder should use another card.
518	An expired card has been entered	The card is expired or the date is incorrect. The cardholder must check that the date is correct or retry using another card.
519	An error occurred when processing the operation. Try again	The cardholder must retry the transaction.
520	The cardholder name entered is not correct	Enter again the cardholder name and retry.
521	The cardholder last name entered is not correct	Enter again the cardholder last name and retry.
522	The email address entered is not valid.	Enter again the cardholder’s email address and retry.
523	The IP address number is incorrect.	Verify that the transaction is taking place from a valid IP address.
524	The identification number entered is incorrect.	Enter again the cardholder’s type and identification number and retry.
525	The encrypted information is not valid	The process of information encryption was not correctly completed. Contact Kushki’s support team so we can review your case.
526	This business has no permission to process transactions	This is caused by a restriction of a business by the payment processor. Contact Kushki’s support team so we can review your case.
527	The entered amount cannot be zero	The amount for this transaction cannot be zero. A different amount must be entered and retry.
528	The transaction amount is different to the initial sale amount	The amount entered in the token must be equal to that of the purchase. It will be necessary to ensure that the amount to pay is correct.
529	It has not been possible to find the transaction	When reversing or cancelling a transaction it was not possible to find the original message. Contact Kushki’s support team so we can review your case.
530	Transaction rejected due to a formatting error	At the time of making the transaction a format error occured. Contact Kushki’s support team so we can review your case.
541	This card has been reported as lost	The cardholder must use a different card to process the transaction and contact the card issuer to review the case.
543	This card has been reported as stolen	The cardholder must use a different card to process the transaction and contact the card issuer to review the case.
551	There are not enough funds to complete the operation.	The cardholder must use a different card to process the transaction as the card entered does not have enough funds the transaction to be processed.
552	The type of account entered is not valid	The cardholder must verify the type of account selected and try again.
553	The card is not compatible	The card brand entered is not compatible for its authorization. The cardholder must use a different card to process the transaction.
554	The type of currency is not valid	The payment processor or card issuer does not accept transactions in the selected currency. Contact Kushki’s support team so we can review your case.
555	The request is not valid	A request issue has occurred for the transaction made. Contact Kushki’s support team so we can review your case.
556	The transaction has been canceled	The transaction that is being reverted or cancelled has already been cancelled
557	The card issuer cannot authorize this transaction	Due to some issuer restrictions, it is not possible to authorize the transaction. The cardholder must change the card or payment method and get in touch with the card issuer to review the case.
558	Transaction not allowed for this business	Due to restrictions by the payment processor it is not possible to authorize the transaction for this business. Contact Kushki’s support team so we can review your case.
559	The transaction has been considered as potentially fraudulent	The transaction made was declined by the payment processor or card issuer due to fraud suspicions.
560	The amount entered is lower or greater than allowed	The amount in the transaction is lower or greater than the limits that have been established. The cardholder must verify the transaction amount and retry.
561	The daily transaction limit has been exceeded	The cardholder has exceeded the activity limit in number or amount of daily transactions
562	Card restricted by the issuing bank	The card issuer has declined the transaction because it has applied restrictions to the cardholder. The cardholder must contact the card issuing bank to review his/her case.
563	Operation rejected due to security breach	The card issuer or payment processor declined the transaction because a security breach occurred.
564	The entered token is not valid or has expired	The token that is being used does not have a valid format, it does not exist or was already used in a transaction
565	The transaction was declined according to security rules	The transaction is being declined because security rules have been established for the card or the merchant
566	The token is not valid, or was already used in another transaction	The token that is being used does not have a valid format, it does not exist or was already used in a transaction. Contact Kushki’s support team so we can review your case.
567	The transaction amount is required	It is mandatory to enter a value in the field “amount”.
568	The transaction ticket number is not valid	Enter again the ticket number; if the issue persists, contact Kushki’s support team so we can review your case.
579	The expiration date entered is incorrect	The cardholder must enter again the expiration date and try again.
580	The deferred payment is not correct	The type or format of the deferred payment that is being used is not correct. Contact Kushki’s support team so we can review your case.
581	Credentials are not correct	Verify your entered credentials and try again
582	The security number (CVV2) is not correct	The cardholder must enter again the security code and retry the transaction.
583	The operation was already cancelled or the maximum time for reversal has been reached	It is not possible to cancel or reverse the transaction because it has been already canceled, the original transaction was not found, or the maximum time allowed to reverse the transaction has ended. Contact Kushki’s support team so we can review your case.
591	Unauthorized Transaction. Inoperative card issuer	The cardholder must wait a couple of minutes and retry; otherwise, an alternative card should be used.
594	The rejected transaction seems to be a duplicate operation	The transaction was declined because a coincidence was found with another previous transaction. This usually happens because a repeated reference number is being entered.
596	The card issuer has had a problem when authorizing the transaction.	The cardholder must wait a couple of minutes and retry; otherwise, an alternative card should be used, or the cardholder should get in contact with the card issuer to verify the case.

HTTP status codes

Kushki will be able to return different HTTP status codes depending on the requests made. There are five categories of standard responses, described in the following image:

HTTP status codes en 800

Below are the most common HTTP status codes, their associated standard message, as well as a more detailed description of the response.

Code	Message	Detail
200	OK	The process was successful. Everything worked as expected, according to the HTTP method
400	Bad Request	The server cannot interpret the request (incorrect syntax, too large size, missing parameters)
401	Authorization Required	Credentials must be authenticated, or authentication has failed
403	Forbidden	Do not have the necessary permissions to perform this action
404	Not Found	Resource or page not found
409	Conflict	The request cannot be processed because of a conflict with the resource (e.g., multiple simultaneous updates)
410	Gone	The requested resource has been deleted from the server, and will no longer be available
429	Too Many Requests	Too many requests have been sent in a short period of time
430	Request Header Fields Too Large	Unofficial code, applies only to Shopify. Similar to code 429
500	Internal Server Error	An unexpected server-side error occurred
502	Bad Gateway	The server (acting as a proxy or gateway) received an invalid response from another server
503	Service Temporarily Unavailable	The server is unavailable (usually because it is under maintenance, or because it is overloaded)
504	Gateway Timeout	The server (acting as a proxy or gateway) has not received a response from the other server in time