Error Codes

Learn about common error responses and how to solve them

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 one-time card payments

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": "ID de comercio o credencial no válido",
"code": "K004" }

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

codemessageWhat to do?
006Abandoned transaction-
017Invalid cardTry another card
201Invalid merchant IDCheck submitted credentials and retry
228Processor unreachableUnable to communicate with processor
228Processor unreachableUnable to communicate with processor
577The transaction token is invalidSubmit the data again to obtain a new token
621Transaction canceled by user-
622Session timeoutRetry transaction
703Transaction amount is requiredMake sure to submit the amount and retry
K001Invalid request bodyCheck request body
K002An unexpected error has occurredRetry the transaction; in case the error persists, get in touch with Kushki’s support team so that we can review your case.
K003Processor does not existContact Kushki’s support team, so we can review your case
K004Invalid merchant IDCheck public merchant ID or private merchant ID and retry
K005Invalid processor IDContact Kushki’s support team, so we can review your case
K007Card blocked by the issuerTry another card
K008Incorrect tokenFill in the data again and retry
K009Check SSM variablesFill in the data again and retry
K011Invalid BINTry another card
K012Invalid capture amountCheck amount to capture and retry
K013Transaction tokenized as deferredVerify that installments’ information has already been submitted in the collection request
K015CVV2_REJECTED_TRANSACTIONCheck the CVV and retry
K016Method not implementedContact Kushki’s support team, so we can review your case
K020ERROR_REJECTED_TRANSACTIONRetry the transaction; in case the error persists, contact Kushki’s support team, so we can review your case
K021ERROR_REJECTED_TRANSACTIONRetry the transaction; in case the error persists, contact Kushki’s support team, so we can review your case
K023Void amount higher than saleThis message is displayed when trying to make a partial void, but the amount is higher than the sale amount
K025Invalid cardTry another card
K026Processor DeclinedContact Kushki’s support team, so we can review your case
K027The transaction went into timeout, please try againRetry the transaction
K028The merchant does not have the deferred option enabled-
K029Invalid card BINTry another card
K030Processor unreachableRetry the transaction
K038Partial void cannot be performed without specifying the value to be deductedSpecify the amount object
K039The sum of the values of the amount property must be greater than 0An amount greater than 0 must be submitted in the amount property.
K040The merchant ID does not match the credential submittedAn amount greater than 0 must be submitted in the amount property.
K041Transaction not allowedContact Kushki’s support team, so we can review your case
K042The 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.
K047An unexpected error has occurredRetry the transaction
K048Token expiredSubmit the data and retry the transaction
K049Previously used tokenSubmit the data and retry the transaction
K220The transaction amount is different to the initial sale amountThe amount submitted in the token must be equal to that of the purchase. It will be necessary to ensure that the amount to pay is correct.
K322Rejected TransactionThe transaction was declined by a Kushki’s security rule. Contact Kushki’s support team so that we can review your case

OTP Authentication Error Codes

Transactions declined by security rules in Kushki will have a K322 code as a generic response. In case the OTP authentication fails, in your Console you will be able to check in the transaction module the reason for declination by opening the transaction detail which will have a declination subcode K326.

Follow the instructions below to view the OTP authentication details:

  1. Login to your console with a Reader User or Master User.
  2. Go to the Transactions>>Cashouts module.
  3. Use the available filters to search for the desired transaction.
  4. Click on the transaction. The Transaction Detail window will open.
  5. The Authentication details section will appear at the bottom of the detail. From there you will be able to view the reason for the declination.

The following GIF will guide you through the authentication detail review process:

Códigos de error OTP

Authentication error codeDescription
K326Authentication failed - Incorrect Key
K326Authentication failed - Attempts Exceeded
K326Authentication failed - Abort
K326Authentication failed - Authentication Error

3DS authentication error codes

Transactions declined by security rules in Kushki will have a K322 code as generic response. In case the 3DS authentication fails, in your Console you will be able to consult in the transaction module the reason for declination by opening the transaction detail which will have a declination subcode K325.

Follow the instructions below to view the 3DS authentication details:

Login to your console with a Reader User or Master User.

  1. Go to the Transactions>>Cashouts module.
  2. Use the available filters to search for the desired transaction.
  3. Click on the transaction. The Transaction Detail window will open.
  4. The Authentication details section will appear at the bottom of the detail.
  5. From there you will be able to view the reason for the declination.

The following GIF will walk you through the authentication detail review process:

Códigos de error 3DS

Authentication error code
K325Authentication failed - Card is not participating in 3DS program
K325Authentication failed - Incomplete information
K325Authentication failed - Invalid information
K325Authentication failed - System Error
K325Authentication failed - Abort
K325Authentication failed - Incorrect OTP or Authentication window closing on challenge
K325Authentication failed - Failed to respond to challenge
K325Authentication Failed - System error due to time out

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.

processorErrormessageWhat to do?
501Rejected transaction. Contact your card issuerThe cardholder must contact his/her card issuer to understand why the transaction was rejected
503The business number is not registeredThe 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.
504The card entered has been reported.The cardholder must use a different card to process the transaction and contact his/her card issuer for them to review the case.
505The transaction was declined by the processor or issuer.The cardholder must wait a couple of minutes and retry; otherwise, he/she must use an alternative card.
512Transaction 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.
513The amount entered contains an invalid syntaxIt 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.
514The card number entered is not validThe cardholder must verify that the card number has been entered correctly and retry.
515The card issuer cannot authorize this transactionThe payment processor or card network rejected the submitted BIN. The cardholder should use another card.
518An expired card has been enteredThe card is expired or the date is incorrect. The cardholder must check that the date is correct or retry using another card.
519An error occurred when processing the operation. Try againThe cardholder must retry the transaction.
520The cardholder name entered is not correctEnter again the cardholder name and retry.
521The cardholder last name entered is not correctEnter again the cardholder last name and retry.
522The email address entered is not valid.Enter again the cardholder’s email address and retry.
523The IP address number is incorrect.Verify that the transaction is taking place from a valid IP address.
524The identification number entered is incorrect.Enter again the cardholder’s type and identification number and retry.
525The encrypted information is not validThe process of information encryption was not correctly completed. Contact Kushki’s support team so we can review your case.
526This business has no permission to process transactionsThis is caused by a restriction of a business by the payment processor. Contact Kushki’s support team so we can review your case.
527The entered amount cannot be zeroThe amount for this transaction cannot be zero. A different amount must be entered and retry.
528The transaction amount is different to the initial sale amountThe 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.
529It has not been possible to find the transactionWhen 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.
530Transaction rejected due to a formatting errorAt the time of making the transaction a format error occured. Contact Kushki’s support team so we can review your case.
541This card has been reported as lostThe cardholder must use a different card to process the transaction and contact the card issuer to review the case.
543This card has been reported as stolenThe cardholder must use a different card to process the transaction and contact the card issuer to review the case.
551There 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.
552The type of account entered is not validThe cardholder must verify the type of account selected and try again.
553The card is not compatibleThe card brand entered is not compatible for its authorization. The cardholder must use a different card to process the transaction.
554The type of currency is not validThe payment processor or card issuer does not accept transactions in the selected currency. Contact Kushki’s support team so we can review your case.
555The request is not validA request issue has occurred for the transaction made. Contact Kushki’s support team so we can review your case.
556The transaction has been canceledThe transaction that is being reverted or cancelled has already been cancelled
557The card issuer cannot authorize this transactionDue 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.
558Transaction not allowed for this businessDue 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.
559The transaction has been considered as potentially fraudulentThe transaction made was declined by the payment processor or card issuer due to fraud suspicions.
560The amount entered is lower or greater than allowedThe amount in the transaction is lower or greater than the limits that have been established. The cardholder must verify the transaction amount and retry.
561The daily transaction limit has been exceededThe cardholder has exceeded the activity limit in number or amount of daily transactions
562Card restricted by the issuing bankThe 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.
563Operation rejected due to security breachThe card issuer or payment processor declined the transaction because a security breach occurred.
564The entered token is not valid or has expiredThe token that is being used does not have a valid format, it does not exist or was already used in a transaction
565The transaction was declined according to security rulesThe transaction is being declined because security rules have been established for the card or the merchant
566The token is not valid, or was already used in another transactionThe 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.
567The transaction amount is requiredIt is mandatory to enter a value in the field “amount”.
568The transaction ticket number is not validEnter again the ticket number; if the issue persists, contact Kushki’s support team so we can review your case.
579The expiration date entered is incorrectThe cardholder must enter again the expiration date and try again.
580The deferred payment is not correctThe 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.
581Credentials are not correctVerify your entered credentials and try again
582The security number (CVV2) is not correctThe cardholder must enter again the security code and retry the transaction.
583The operation was already cancelled or the maximum time for reversal has been reachedIt 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.
591Unauthorized Transaction. Inoperative card issuerThe cardholder must wait a couple of minutes and retry; otherwise, an alternative card should be used.
594The rejected transaction seems to be a duplicate operationThe transaction was declined because a coincidence was found with another previous transaction. This usually happens because a repeated reference number is being entered.
596The 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.

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.

codemessageWhat to do?
K001Invalid request bodyCheck request body
K003Error in gateway responseRetry, in case the error persists, contact Kushki’s support team, so we can review your case
K004Invalid merchant IDCheck public merchant ID or private merchant ID and retry
K007Card blocked by the issuerTry another card
K008Incorrect tokenFill in the data again and retry
K010Merchant not eligible for subscriptionsContact Kushki’s support team, so we can review your case
K011Invalid start dateCheck the start date submitted in the startDate variable
K012Invalid subscription IDCheck amount to capture and retry
K013Invalid end dateCheck the date submitted in the endDate variable
K014Invalid capture amountCheck amount to capture and retry
K015Transaction not allowed without CCV2Check CVV and retry
K016Unable to update subscriptionCheck information submitted and retry
K020ERROR_REJECTED_TRANSACTIONRetry the transaction; in case the error persists, contact Kushki’s support team, so we can review your case
K021ERROR_REJECTED_TRANSACTIONRetry the transaction; in case the error persists, contact Kushki’s support team, so we can review your case
K022Previously used tokenSubmit the data again and retry
K023Void amount higher than saleThis message is displayed when trying to make a partial void, but the amount is higher than the sale amount
K024Amount value must be greater than zeroCheck amount submitted and retry
K025Invalid cardTry another card
K026Merchant disabledContact Kushki’s support team, so we can review your case
K027Unable to complete transactionRetry transaction
K028Processor DeclinedContact Kushki’s support team, so we can review your case
K029Card details do not match in the subscription and its confirmationCheck the details submitted and retry
K031No webpay subscription to confirmCheck the subscription ID submitted and retry
K032The webpay subscription has been previously confirmed-
K034No processors existContact Kushki’s support team, so we can review your case
K035Processor not availableRetry. If the error persists, contact Kushki’s support team, so we can review your case
K036Third party integration errorContact Kushki’s support team, so we can review your case
K037Subscription not foundCheck the subscription ID submitted and try again
K038Partial void cannot be performed without specifying the value to be deductedSpecify the amount object
K039The sum of the values of the amount property must be greater than 0An amount greater than 0 must be submitted in the amount property.
K040The merchant ID does not match the credential submittedAn amount greater than 0 must be submitted in the amount property.
K041Transaction not allowedContact Kushki’s support team, so we can review your case
K042The 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.
K043Preauthorization transaction does not match subscriptionCheck submitted information and try again
K044The entered BIN does not support this payment methodTry another card
K045Capture transaction previously performedCapture cannot be performed again
K046The transaction went into timeout, please try againRetry the transaction
K047An unexpected error has occurredRetry the transaction
K048Processor does not support the current methodContact Kushki’s support team, so we can review your case
K049Card expiredTry another card
K050This token is no longer validCheck the data submitted and retry
K051The merchant does not have the deferred option enabledContact Kushki’s support team, so we can review your case
K052ERROR_REJECTED_TRANSACTIONRetry the transaction; in case the error persists, contact Kushki’s support team, so we can review your case
K027The transaction went into timeout, please try againRetry the transaction

3DS authentication error codes

Transactions declined by security rules in Kushki will have a K322 code as generic response. In case the 3DS authentication fails, in your Console you will be able to consult in the transaction module the reason for declination by opening the transaction detail which will have a declination subcode K325.

Follow the instructions below to view the 3DS authentication details:

Login to your console with a Reader User or Master User.

  1. Go to the Transactions>>Cashouts module.
  2. Use the available filters to search for the desired transaction.
  3. Click on the transaction. The Transaction Detail window will open.
  4. The Authentication details section will appear at the bottom of the detail.
  5. From there you will be able to view the reason for the declination.

The following GIF will walk you through the authentication detail review process:

Códigos de error 3DS

Authentication error code
K325Authentication failed - Card is not participating in 3DS program
K325Authentication failed - Incomplete information
K325Authentication failed - Invalid information
K325Authentication failed - System Error
K325Authentication failed - Abort
K325Authentication failed - Incorrect OTP or Authentication window closing on challenge
K325Authentication failed - Failed to respond to challenge
K325Authentication Failed - System error due to time out

Codes returned by Kushki for cash payments

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": "ID de comercio o credencial no válido",
"code": "K004" }

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

codemessageWhat to do?
K001Invalid request bodyCheck request body
K002An unexpected error has occurredRetry the transaction; in case the error persists, get in touch with Kushki’s support team so that we can review your case.
K003Invalid tokenFill in the data again and retry
K004Invalid merchant IDCheck public merchant ID or private merchant ID and retry
K005Invalid transaction IDFill in the data again and retry
K006Invalid transaction amountCheck amount to capture and retry
K007Pin submitted does not existCheck pin and retry
K008Transaction is in an invalid statusVerify that the transaction has not been previously paid or voided
K009Pin is already in paid statusPayment has been made previously
K010Third party integration errorContact Kushki’s support team, so we can review your case
K011Error. No attachments in the emailTry another card
K012Invalid transaction statusCheck amount to capture and retry
K017The expiration date is not validContact Kushki’s support team, so we can review your case
K018Transaction does not exist or has been deletedContact Kushki’s support team, so we can review your case
K019Merchant has no businessIdContact Kushki’s support team, so we can review your case
K021No records were found for the search criteria.Retry the transaction; in case the error persists, contact Kushki’s support team so that we can review your case.
K022Unable to delete this transactionContact Kushki’s support team so that we can review your case
K023Unable to update the transactionThis message is displayed when trying to make a partial void, but the amount is higher than the sale amount
K025The merchant does not have any processors availableContact Kushki’s support team so that we can review your case
K026Request signature validation failedRetry transaction
K032No payment networks existContact Kushki’s support team, so we can review your case
K033Transaction previously cancelledTransaction already cancelled
K034Stone webhook validation error-
K035Pin generated by the processor duplicatedPin is duplicated, try to generate a new pin
K036Transaction can no longer be reversedThe transaction is in a status in which it cannot be reversed
K037The transaction went into timeout, please try againRetry the transaction
K038Processor does not existContact Kushki’s support team, so we can review your case
K040The merchant ID does not match the credential submittedAn amount greater than 0 must be submitted in the amount property.
K041The merchant does not have any processors availableContact Kushki’s support team so that we can review your case

Codes returned by Kushki for wire transfer distribution

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": "Transacción rechazada",
"code": "501" }

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

codemessageWhat to do?
501Transaction rejectedYou should contact the account issuer to find out why the transaction was rejected.
530Transaction rejected; information errorAt the time of the transaction there was an error in the transaction format. Contact Kushki’s support team, so we can review your case.
514The account entered is invalidVerify that the account number has been entered correctly, that it corresponds to the issuing bank and retry.
594Duplicate transactionThe transaction was declined because there is a match with a previous transaction. This usually happens because a repeated reference number is being entered.
524Invalid document numberRe-enter the type and ID number corresponding to the account and retry.
518The account type is invalidVerify that the account type entered is correct and retry.
517The transaction type is invalidVerify that the transaction type to be performed is correct and retry.
516The payment type is invalidVerify that the payment type is correct and corresponds to the account type and retry.
513Amount has invalid syntaxIt 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.
596Transaction rejected due to third party restrictionsYou will need to wait a couple of minutes and retry, otherwise use an alternate account or contact the account issuer to verify.
515Transaction rejected by beneficiaryYou should contact the account issuer to find out why the transaction was rejected.
560Amount entered exceeds limitYou must verify that the authorized balance limit of the account or the limit of credits allowed in the month in the account have not been exceeded. You will need to contact the account issuer to know the reasons or use another account.

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.

CodeMessageDetail
200OKThe process was successful. Everything worked as expected, according to the HTTP method
400Bad RequestThe server cannot interpret the request (incorrect syntax, too large size, missing parameters)
401Authorization RequiredCredentials must be authenticated, or authentication has failed
403ForbiddenDo not have the necessary permissions to perform this action
404Not FoundResource or page not found
409ConflictThe request cannot be processed because of a conflict with the resource (e.g., multiple simultaneous updates)
410GoneThe requested resource has been deleted from the server, and will no longer be available
429Too Many RequestsToo many requests have been sent in a short period of time
430Request Header Fields Too LargeUnofficial code, applies only to Shopify. Similar to code 429
500Internal Server ErrorAn unexpected server-side error occurred
502Bad GatewayThe server (acting as a proxy or gateway) received an invalid response from another server
503Service Temporarily UnavailableThe server is unavailable (usually because it is under maintenance, or because it is overloaded)
504Gateway TimeoutThe server (acting as a proxy or gateway) has not received a response from the other server in time