Ecommerce API: Error codes

United States
Canada

The Ecommerce API returns error codes and messages when a request contains invalid or incomplete data and Clover cannot process the request. These issues can be divided into two general categories:

  • Errors that should be addressed by your app's logic (if you are integrating with the API only)
  • Errors that should be handled at runtime (iframe and API integrations)

Errors you may encounter are explained the in the following sections.

API only errors

You can prevent these errors by checking for the described issues in your application before submitting the API request.

Error codeDescriptionRequest type(s)Prevention
incorrect_cvcThe card.cvv provided is not a three- or four-digit valueCreate tokenVerify that the CVV value is a three- or four-digit number
invalid_cvcThe card.cvv provided is not a three- or four-digit valueCreate token, create or update customerVerify that the CVV value is a three- or four-digit number
invalid_expiry_monthThe card.exp_month provided is not a one- or two-digit valueCreate tokenVerify that the month value is a one- or two-digit number
invalid_expiry_yearThe card.exp_month provided is not a two- or four-digit valueCreate tokenVerify that the year value is a two- or four-digit number
invalid_numberThe PAN provided in card.number is invalidCreate tokenVerify that the PAN is valid
invalid_tax_amountThe tax_amount provided is not validCreate chargeVerify that the amount is a positive number

API and iframe errors

These errors can be handled at runtime and may be encountered by any Ecommerce app.

Error codeDescriptionRequest typeNext steps
amount_too_largeThe amount provided exceeds the amount allowed by Clover ($999, 999.99)Create charge and pay for orderIf possible, split the charge or order into smaller amounts and retry as two transactions. If the customer's source token is single-use, the card will need to be tokenized again before attempting a second request when the first succeeds.
card_declinedThe source provided was declined by the payment gatewayCreate charge and pay for orderAllow the customer to enter a different card and retry the request with the new source
card_on_file_missingThe customer attempting to pay does not have a source on file to complete the paymentChargeDirect the customer to enter their card information and update the customer's record with the new source. Then, retry the original charge request.
charge_already_capturedThe charge provided has already been capturedCapture chargeDo not retry the request
charge_already_refundedThe charge provided has already been refundedRefundDo not retry the request
email_invalidThe email provided is not validCreate charge, create or update customer, pay for orderNotify the customer of the issue and allow them to retry or enter a new email address
expired_cardThe expiration date (the combination of card.exp_month and card.exp_year) provided is in the pastTokenNotify the customer of the issue and allow them to retry by entering a new card
incorrect_cvcThe card.cvv provided is not a three- or four-digit valueTokenNotify the customer of the issue and allow them to retry by entering a new card
incorrect_numberThe value provided in card.number is not validTokenNotify the customer of the issue and allow them to retry by entering a new card
invalid_card_typeThe card.brand provided is not a recognized valueTokenBefore sending the request, verify that the brand is one of the enumerated values
invalid_charge_amountThe amount provided exceeds the amount allowed by CloverChargeIf possible, split the charge or order into smaller amounts and retry as two transactions. If the customer's source token is single-use, the card will need to be tokenized again before attempting a second request when the first succeeds.
invalid_requestThe value provided in card.number is not a valid raw or encrypted PANTokenNotify the customer of the issue and allow them to retry by entering a new card
invalid_tip_amountThe tip_amount provided is not a valid amountCreate charge and pay for orderNotify the customer of the issue and allow them to retry by entering a new tip amount
invalid_tax_amountThe tax_amount provided is not a valid amountCreate chargeCheck that the amount is a positive number and, if the value has changed after the check, retry the request
missingThe token request failed upstream and the upstream message could not be processedTokenAllow the user to retry the transaction
order_already_paidThe order identified by the ID in the request URL has already been paidPay orderNotify the user that the order has already been paid
processing_errorA generic error indicating that the request could not be processed as submittedAnyNotify the user that an error occurred and, if warranted, allow them to retry the request
rate_limitYour application has made too many requests and additional requests will not be processed until the rate limit expiresAnyFollow the best practices described in API usage & rate limits
resource_missingThe data item (charge, order, or refund) provided in the request does not existAnyNotify the user that the data item could not be found. Allow the user to adjust the request and retry.
token_already_usedThe source value is not a multipay token and was already used for a different paymentChargeNotify the user of the issue and have them reenter their card details. Then, use the iframe to generate a new token.