Chile
Colombia
Ecuador
Peru
Error Codes
November 15, 2023Learn 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.
| code | message | What to do? |
|---|---|---|
| 006 | Abandoned transaction | - |
| 017 | Invalid card | Try another card |
| 201 | Invalid merchant ID | Check submitted credentials and retry |
| 228 | Processor unreachable | Unable to communicate with processor |
| 228 | Processor unreachable | Unable to communicate with processor |
| 577 | The transaction token is invalid | Submit the data again to obtain a new token |
| 621 | Transaction canceled by user | - |
| 622 | Session timeout | Retry transaction |
| 703 | Transaction amount is required | Make sure to submit the amount and retry |
| K001 | Invalid request body | Check request body |
| K002 | An unexpected error has occurred | Retry the transaction; in case the error persists, get in touch with Kushki’s support team so that we can review your case. |
| K003 | Processor does not exist | 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 |
| K005 | Invalid processor ID | Contact Kushki’s support team, so we can review your case |
| K006 | Rejected subscription 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 |
| K009 | Check SSM variables | Fill in the data again and retry |
| K011 | Invalid BIN | Try another card |
| K012 | Invalid capture amount | Check amount to capture and retry |
| K013 | Transaction tokenized as deferred | Verify that installments’ information has already been submitted in the collection request |
| K015 | CVV2_REJECTED_TRANSACTION | Check the CVV and retry |
| K016 | Method not implemented | Contact Kushki’s support team, so we can review your case |
| 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 |
| K025 | Invalid card | Try another card |
| K026 | Processor Declined | Contact Kushki’s support team, so we can review your case |
| K027 | The transaction went into timeout, please try again | Retry the transaction |
| K028 | The merchant does not have the deferred option enabled | - |
| K029 | Invalid card BIN | Try another card |
| K030 | Processor unreachable | Retry the transaction |
| 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. |
| K047 | An unexpected error has occurred | Retry the transaction |
| K048 | Token expired | Submit the data and retry the transaction |
| K049 | Previously used token | Submit the data and retry the transaction |
| K220 | The transaction amount is different to the initial sale amount | The 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. |
| K322 | Rejected Transaction | The 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:
- Login to your console with a Reader User or Master User.
- Go to the Transactions>>Cashouts module.
- Use the available filters to search for the desired transaction.
- Click on the transaction. The Transaction Detail window will open.
- 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:
| Authentication error code | Description | |
|---|---|---|
| K326 | Authentication failed - Incorrect Key | |
| K326 | Authentication failed - Attempts Exceeded | |
| K326 | Authentication failed - Abort | |
| K326 | Authentication 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.
- Go to the Transactions>>Cashouts module.
- Use the available filters to search for the desired transaction.
- Click on the transaction. The Transaction Detail window will open.
- 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 walk you through the authentication detail review process:
| Authentication error code | |
|---|---|
| K325 | Authentication failed - Card is not participating in 3DS program |
| K325 | Authentication failed - Incomplete information |
| K325 | Authentication failed - Invalid information |
| K325 | Authentication failed - System Error |
| K325 | Authentication failed - Abort |
| K325 | Authentication failed - Incorrect OTP or Authentication window closing on challenge |
| K325 | Authentication failed - Failed to respond to challenge |
| K325 | Authentication Failed - System error due to time out |
| K325 | Autenticación externa fallida - Datos enviados por comercio no son seguros |
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 his/her 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, he/she 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. |
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 |
| K007 | Card blocked by the issuer | Try another card |
| K006 | Subscription rejected due to collection validation | Retry transaction |
| 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 |
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.
- Go to the Transactions>>Cashouts module.
- Use the available filters to search for the desired transaction.
- Click on the transaction. The Transaction Detail window will open.
- 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 walk you through the authentication detail review process:
| Authentication error code | |
|---|---|
| K325 | Authentication failed - Card is not participating in 3DS program |
| K325 | Authentication failed - Incomplete information |
| K325 | Authentication failed - Invalid information |
| K325 | Authentication failed - System Error |
| K325 | Authentication failed - Abort |
| K325 | Authentication failed - Incorrect OTP or Authentication window closing on challenge |
| K325 | Authentication failed - Failed to respond to challenge |
| K325 | Authentication Failed - System error due to time out |
| K325 | Autenticación externa fallida - Datos enviados por comercio no son seguros |
Codes returned by Kushki for cash payments
Check our article about error codes for declined cash transactions.
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.
| code | message | What to do? |
|---|---|---|
| 501 | Transaction rejected | You should contact the account issuer to find out why the transaction was rejected. |
| 530 | Transaction rejected; information error | At the time of the transaction there was an error in the transaction format. Contact Kushki’s support team, so we can review your case. |
| 514 | The account entered is invalid | Verify that the account number has been entered correctly, that it corresponds to the issuing bank and retry. |
| 594 | Duplicate transaction | The transaction was declined because there is a match with a previous transaction. This usually happens because a repeated reference number is being entered. |
| 524 | Invalid document number | Re-enter the type and ID number corresponding to the account and retry. |
| 518 | The account type is invalid | Verify that the account type entered is correct and retry. |
| 517 | The transaction type is invalid | Verify that the transaction type to be performed is correct and retry. |
| 516 | The payment type is invalid | Verify that the payment type is correct and corresponds to the account type and retry. |
| 513 | Amount has 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. |
| 596 | Transaction rejected due to third party restrictions | You will need to wait a couple of minutes and retry, otherwise use an alternate account or contact the account issuer to verify. |
| 515 | Transaction rejected by beneficiary | You should contact the account issuer to find out why the transaction was rejected. |
| 560 | Amount entered exceeds limit | You 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:
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 |