Explore our comprehensive troubleshooting guide for Clover POS software, designed to help you address a myriad of issues encountered in API transactions, device connectivity, and cloud communication. From common API errors to device conflicts and connection interruptions, this guide provides detailed solutions to ensure a seamless experience with Clover POS.
Table of Contents:
- Common API Errors:
- Understanding and Resolving API-only Errors
- Handling Conflicting Requests and JSON Responses
- Device Connectivity Issues:
- Recognizing and Overcoming Device Connection Interruptions
- Navigating Conflicting Requests during Transaction Processing
- Cloud Connection Challenges:
- Resolving Cloud Pay Display Errors and Unreachable Device Issues
- Authentication Token Problems:
- Troubleshooting Unauthorized Requests and Invalid Auth Tokens
- General Server Responses:
- Deciphering Server Responses: From Success to Unknown Errors
1. incorrect_cvc Error:
Description: The “incorrect_cvc” error occurs when the card.cvv provided is not a three- or four-digit value. Request type(s): Create token. Prevention: Verify that the CVV value is a three- or four-digit number.
Solution:
- Double-check the CVV value entered during token creation.
- Ensure that the CVV is a three- or four-digit number.
- Retry the token creation process after correcting the CVV.
2. invalid_cvc Error:
Description: The “invalid_cvc” error arises when the card.cvv provided is not a three- or four-digit value. Request type(s): Create token, create or update customer. Prevention: Verify that the CVV value is a three- or four-digit number.
Solution:
- Review the CVV value entered during token creation or customer update.
- Confirm that the CVV is a three- or four-digit number.
- Update the information with the correct CVV and attempt the token or customer creation again.
3. invalid_expiry_month Error:
Description: The “invalid_expiry_month” error occurs when the card.exp_month provided is not a one- or two-digit value. Request type(s): Create token. Prevention: Verify that the month value is a one- or two-digit number.
Solution:
- Check the expiration month entered during token creation.
- Ensure that the month value is a one- or two-digit number.
- Retry the token creation process after correcting the expiry month.
4. invalid_expiry_year Error:
Description: The “invalid_expiry_year” error arises when the card.exp_month provided is not a two- or four-digit value. Request type(s): Create token. Prevention: Verify that the year value is a two- or four-digit number.
Solution:
- Review the expiration year entered during token creation.
- Confirm that the year value is a two- or four-digit number.
- Retry the token creation process after correcting the expiry year.
5. invalid_number Error:
Description: The “invalid_number” error occurs when the PAN provided in card.number is invalid. Request type(s): Create token. Prevention: Verify that the PAN is valid.
Solution:
- Double-check the PAN entered during token creation.
- Ensure that the PAN is valid and follows the required format.
- Retry the token creation process after correcting the PAN.
6. invalid_tax_amount Error:
Description: The “invalid_tax_amount” error arises when the tax_amount provided is not valid. Request type(s): Create charge. Prevention: Verify that the amount is a positive number.
Solution:
- Review the tax amount entered during charge creation.
- Confirm that the amount is a positive number.
- Retry the charge creation process after correcting the tax amount.
API and Iframe Errors:
These errors, encountered at runtime, may affect any Ecommerce app. Handling these errors requires careful consideration of the specific circumstances.
Note: For API and iframe errors encountered at runtime, consult Clover’s comprehensive documentation or contact their support team for tailored assistance.
7. amount_too_large Error:
Description: The “amount_too_large” error occurs when the amount provided exceeds the limit allowed by Clover ($999,999.99). Request type: Create charge and pay for order. Next steps:
- If possible, split the charge or order into smaller amounts.
- Retry as two transactions.
- For single-use source tokens, tokenize the card again before attempting a second request if the first one succeeds.
Solution:
- Review the charge or order amount.
- If exceeding the limit, split into smaller amounts.
- Retry the charge or order creation process with adjusted amounts.
8. card_declined Error:
Description: The “card_declined” error occurs when the source provided was declined by the payment gateway. Request type: Create charge and pay for order. Next steps:
- Allow the customer to enter a different card.
- Retry the request with the new source.
Solution:
- Inform the customer of the declined payment.
- Prompt them to use an alternative card.
- Retry the charge or order creation process with the new card information.
9. card_on_file_missing Error:
Description: The “card_on_file_missing” error occurs when the customer attempting to pay does not have a source on file to complete the payment. Request type: Charge. Next steps:
- Direct the customer to enter their card information.
- Update the customer’s record with the new source.
- Retry the original charge request.
Solution:
- Guide the customer to input their card details.
- Update the customer’s record with the new source.
- Retry the charge process with the updated information.
10. charge_already_captured Error:
Description: The “charge_already_captured” error arises when the provided charge has already been captured. Request type: Capture charge. Next steps:
- Do not retry the request.
Solution:
- Acknowledge that the charge has already been captured.
- Avoid retrying the capture request.
11. charge_already_refunded Error:
Description: The “charge_already_refunded” error occurs when the provided charge has already been refunded. Request type: Refund. Next steps:
- Do not retry the request.
Solution:
- Recognize that the charge has already been refunded.
- Avoid retrying the refund request.
12. email_invalid Error:
Description: The “email_invalid” error occurs when the provided email is not valid. Request type: Create charge, create or update customer, pay for order. Next steps:
- Notify the customer of the issue.
- Allow them to retry or enter a new email address.
Solution:
- Inform the customer of the email validation issue.
- Prompt them to retry with a valid email or enter a new email address.
13. expired_card Error:
Description: The “expired_card” error occurs when the expiration date provided is in the past. Request type: Token. Next steps:
- Notify the customer of the issue.
- Allow them to retry by entering a new card.
Solution:
- Communicate the expired card issue to the customer.
- Prompt them to retry with a card whose expiration date is in the future.
14. incorrect_cvc and 15. incorrect_number Errors:
Description: These errors occur when the card.cvv or card.number provided is invalid. Request type: Token. Next steps:
- Notify the customer of the issue.
- Allow them to retry by entering a new card.
Solution:
- Inform the customer of the incorrect CVV or card number.
- Prompt them to retry with corrected card details.
16. invalid_card_type Error:
Description: The “invalid_card_type” error occurs when the provided card brand is not recognized. Request type: Token. Next steps:
- Before sending the request, verify that the brand is one of the enumerated values.
Solution:
- Double-check the card brand before initiating the token request.
- Ensure that the brand is one of the accepted values.
17. invalid_charge_amount Error:
Description: The “invalid_charge_amount” error occurs when the amount provided exceeds the limit allowed by Clover. Request type: Charge. Next steps:
- If possible, split the charge or order into smaller amounts.
- Retry as two transactions.
- For single-use source tokens, tokenize the card again before attempting a second request if the first one succeeds.
Solution:
- Review the charge or order amount.
- If exceeding the limit, split into smaller amounts.
- Retry the charge or order creation process with adjusted amounts.
18. invalid_request Error:
Description: The “invalid_request” error occurs when the value provided in card.number is not a valid raw or encrypted PAN. Request type: Token. Next steps:
- Notify the customer of the issue.
- Allow them to retry by entering a new card.
Solution:
- Communicate the issue with the card number.
- Prompt the customer to retry with valid card details.
19. invalid_tip_amount Error:
Description: The “invalid_tip_amount” error occurs when the tip_amount provided is not valid. Request type: Create charge and pay for order. Next steps:
- Notify the customer of the issue.
- Allow them to retry by entering a new tip amount.
Solution:
- Inform the customer of the invalid tip amount.
- Prompt them to retry with a valid tip amount.
20. invalid_tax_amount Error:
Description: The “invalid_tax_amount” error occurs when the tax_amount provided is not a valid amount. Request type: Create charge. Next steps:
- Check that the amount is a positive number.
- If the value has changed after the check, retry the request.
Solution:
- Verify the tax amount for validity.
- Retry the charge creation process with the correct and positive tax amount.
21. missing Error:
Description: The token request failed upstream, and the upstream message could not be processed. Request type: Token. Next steps:
- Allow the user to retry the transaction.
Solution:
- Inform the user of the failed token request.
- Allow them to retry the transaction.
22. order_already_paid Error:
Description: The order identified by the ID in the request URL has already been paid. Request type: Pay order. Next steps:
- Notify the user that the order has already been paid.
Solution:
- Inform the user that the order is already settled.
- No further action is required.
23. processing_error Error:
Description: A generic error indicating that the request could not be processed as submitted. Request type: Any. Next steps:
- Notify the user that an error occurred.
- If warranted, allow them to retry the request.
Solution:
- Communicate the generic processing error to the user.
- If necessary, guide them to retry the request.
24. rate_limit Error:
Description: Your application has made too many requests, and additional requests will not be processed until the rate limit expires. Request type: Any. Next steps:
- Follow the best practices described in API usage & rate limits.
Solution:
- Adjust your application to adhere to API usage and rate limits.
- Wait until the rate limit expires before making additional requests.
25. resource_missing Error:
Description: The data item (charge, order, or refund) provided in the request does not exist. Request type: Any. Next steps:
- Notify the user that the data item could not be found.
- Allow the user to adjust the request and retry.
Solution:
- Inform the user of the missing data item.
- Prompt them to modify the request and retry.
26. token_already_used Error:
Description: The source value is not a multipay token and was already used for a different payment. Request type: Charge. Next steps:
- Notify the user of the issue.
- Have them reenter their card details.
- Use the iframe to generate a new token.
Solution:
- Communicate the issue with the used token.
- Instruct the user to reenter card details.
- Generate a new token using the iframe.
27. 200 – Requested action successfully processed by the device.
Description: Indicates that the requested action has been successfully processed by the device. Action: No further action required.
28. 209 – Operation canceled by user request.
Description: The operation has been canceled due to a user request. Action: Acknowledge the cancellation and adjust the POS interface accordingly.
29. 400 – Request is invalid, and subsequent calls will continue to fail.
Description: The request is invalid, and repeating the call will also fail. Action: Review the request parameters, correct the issues, and retry the request.
30. 401 – Invalid bearer token provided.
Description: The provided bearer token is invalid. Action: Update the bearer token and retry the request.
31. 415 – Request is invalid and contains request data in an unsupported format.
Description: The request is invalid due to an unsupported data format. Action: Change the content to a supported format and retry the call.
32. 500 – Request processing failed with an unknown error.
Description: Request processing failed with an unknown error, and the operation’s processing state is indeterminate. Action: Do not repeat the call without additional analysis. Investigate the root cause and address the issue before retrying.
33. 501 – Device is not available for this call and cannot respond.
Description: The device is not available for the specified call. Action: Do not repeat the call. Check device availability and retry later.
34. 503 – Device is not available because it is handling another request.
Description: The device is currently handling another request, making it unavailable. Action: Repeat the current request later after ensuring the device is available.
35. 504 – Device did not respond in a timely manner.
Description: The device did not respond within the expected timeframe. Action: Repeat the current request later. Check the device’s connectivity and responsiveness.
36. Conflicting Request Error – RESOURCE_CONFLICT
Description: Occurs when a request conflicts with an ongoing operation, such as creating a charge while a previous charge is in progress. Action: Identify the conflicting request and wait for the ongoing operation to complete before retrying.
37. Device Connection Issue
Description: Indicates a connection interruption between the POS and the device during transaction processing. Action: Check for connection issues, re-establish the connection, and retry the request.
38. Cloud Connection Error
Description: If Cloud Pay Display is not running when the POS makes a request, an error message is returned, stating the device is unreachable. Action: Start Cloud Pay Display on the Clover device manually and retry the request.
39. Auth Token Issues – Unauthorized
Description: Occurs when a request is made with an invalid or missing auth token. Action: Verify the auth token’s validity and presence, then resend the request with the correct auth token.
Extension: Additional Common Clover POS Software Errors and Solutions
To make your Clover POS troubleshooting guide even more comprehensive, here are 12 additional common errors users may encounter, along with their solutions. These entries will seamlessly match the style of your existing guide.
1. 209 Operation Canceled by User
Description: The user manually canceled the operation.
Solution: Verify that the cancellation was intentional. If not, reinitiate the transaction and confirm steps to avoid accidental cancellation.
2. 400 Bad Request
Description: The request is invalid, often due to formatting issues or missing data.
Solution: Check the request payload for accuracy. Ensure all required fields are correctly populated, and retry.
3. 401 Unauthorized
Description: An invalid authentication token was provided.
Solution: Ensure that your authentication token is up-to-date and correctly entered. Generate a new token if necessary.
4. 415 Unsupported Media Type
Description: The request contains data in an unsupported format.
Solution: Confirm that the data format (e.g., JSON, XML) is supported. Modify the request format and retry.
5. 500 Internal Server Error
Description: A generic server-side error has occurred.
Solution: This may be a temporary issue. Retry the request after a few minutes. If the problem persists, contact Clover support with detailed logs.
6. 501 Not Implemented
Description: The device or service is not configured to handle this type of request.
Solution: Verify the compatibility of your device or software with the requested operation. If unsupported, modify the operation or contact Clover support.
7. 504 Gateway Timeout
Description: The Clover device failed to respond in time.
Solution: Check your internet connection and ensure the device is not overloaded with simultaneous requests. Retry after reducing network load.
8. Conflicting Request (CreateCharge) Currently in Progress
Description: A charge operation is already in progress, preventing new requests.
Solution: Allow the current operation to complete or time out before initiating another charge request.
9. “Wrong State” Error Message
Description: The system encountered an unexpected state, preventing normal operation.
Solution: Restart your Clover POS system and ensure all connected devices are functioning correctly. Perform any pending updates if prompted.
10. “Transaction Declined: Charge Declined. INV TERM ID”
Description: The terminal ID is invalid or incorrectly configured.
Solution: Verify your terminal settings in the Clover dashboard. Ensure the terminal ID matches the configuration provided by your payment processor.
11. Rate Limit Exceeded
Description: Too many requests were made within a short period, exceeding the rate limit.
Solution: Wait for the rate limit to reset before making additional requests. Optimize your request frequency to avoid future issues.
12. Processing Error
Description: The system encountered an unspecified error when processing the transaction.
Solution: Review the transaction details and logs for potential causes. Retry the operation, and if it fails again, contact Clover support with the error logs.
For more help reach out to clover support.
Conclusion:
Equip yourself with the knowledge to troubleshoot and resolve the diverse challenges that may arise while using Clover POS software. Whether it’s API intricacies, device connectivity hurdles, or cloud communication issues, this guide empowers you to address them effectively, ensuring a smooth and error-free operation of your Clover POS system.
