Handling Errors
When working with APIs, errors can occur at various stages, such as HTTP errors and API-specific errors. HTTP status codes, like 2xx for success and 4xx/5xx for errors, indicate the outcome of a request. API errors may result from issues like invalid input, missing parameters, or server-side problems. Understanding these error types helps you manage and respond to issues effectively.
HTTP Status Code
An HTTP status code is a three-digit number returned by a server in response to a client’s request, indicating the outcome of that request. These codes are grouped into categories based on the type of response, helping the client understand whether the request was successful or if there were any errors.
- 2xx: Indicates successful requests.
- 4xx: Represents client-side errors (often caused by incorrect input or parameters).
- 5xx: Denotes server-side errors.
The status codes that are commonly used are listed below:
| Status Code | Description |
|---|---|
| 200 | OK |
| 201 | Created |
| 400 | Bad request |
| 401 | Unauthorized (Invalid AuthToken) |
| 404 | URL not found |
| 405 | Method not allowed (Method you have called is not supported for the invoked API) |
| 429 | Rate limit exceeded (API usage limit exceeded) |
| 500 | Internal error |
All error responses follow the same JSON structure with keys - code and message.
Sample Failure Response
{
"code": "invalid_payment_session",
"message": "Payment session is invalid."
}
Sample Failure Response
{
"code": "invalid_payment_session",
"message": "Payment session is invalid."
}
API Errors
API errors occur when a request cannot be completed as expected, often due to factors like invalid input, missing parameters, or server-side issues. These errors are typically represented by numerical or alphanumeric error codes, which help identify specific problems such as declined payments, insufficient funds, or authentication failures.
Validation Errors
Validation errors occur when invalid values are passed in API requests, leading to validation failures. These can happen if the URL or request parameters are incorrect. Typically, these errors are returned with an HTTP status code in the 4xx range.
They often result from misconfigurations in your integration, such as incorrect URLs or unhandled parameters. Examples include invalid URLs, incorrect currency codes, or invalid resource IDs.
| Error Code | Description | Solution |
|---|---|---|
| resource_does_not_exist | This error typically occurs when the client requests a resource by its unique identifier (e.g., payment_id, refund_id or payment_session_id) that is either incorrect, deleted, or never existed in the system. | Verify the resource ID and ensure it’s valid and exists in the system. |
| invalid_value | This error occurs when a request is rejected due to invalid values that do not meet the expected format, range, or constraints. | Verify and update the values to match the expected format and range. |
| invalid_currency | This error occurs when the currency you have entered is invalid. The accepted currency format is the three-letter ISO code. Ensure that you enter a valid currency code. | Ensure that you enter a valid three-letter ISO currency code (e.g., INR, USD, EUR). |
Payment and Payment Method Errors
Payment and payment method errors occur when issues arise during payment processing. These may result from incorrect payment details, problems on the processor’s or issuer’s end, or conditions such as insufficient funds, unsupported methods.
| Error Code | Description | Solution |
|---|---|---|
| payments_not_enabled | This error occurs when payment methods are not enabled on your account for processing the transaction. | Enable payment methods in your account settings to process the transactions. |
| currency_not_supported _for_payment |
This error occurs when a payment is attempted with a currency that is not supported by Zoho Payments. | Request the customer to use only the supported currencies for payments. |
| refund_cannot_be_initiated | This error occurs when the refund cannot be initiated due to the transaction’s status, exceeding the allowable refund amount, or invalid refund details. | Verify that the transaction is eligible for a refund or contact support@zohopay.com for assistance. |
| amount_too_large | This error occurs when the processing amount exceeds the transaction limit. | Verify the transaction limits and ensure the amount doesn’t exceed the allowed threshold. |
| refunds_not_enabled | This error occurs when the refunds feature is disabled for your account. | Reach out to support@zohopay.com to enable the refunds module. |
| payment_already_failed | This error occurs when the payment has failed and cannot be processed further. | Since the payment failed, a new transaction must be initiated. |
| refund_not_allowed _payment_disputed |
This error occurs when a refund is attempted on a payment that is currently under dispute. | You should wait until the dispute is resolved before attempting a refund. |
| payment_already_refunded | This error occurs when the transaction has already been refunded and cannot be processed further. | A refund has already been processed. No further action can be taken. |
| refund_exceeds_payment _amount |
This error occurs when the requested refund is larger than the amount initially paid. | Ensure the refund amount does not exceed the original payment amount. |
| amount_too_small | This error occurs when the amount is below the transaction minimum limit. | Increase the transaction amount to meet the minimum limit. |
| refund_exceeds_balance _amount |
This error occurs when the requested refund is greater than the available balance for the transaction. | Ensure sufficient funds are available, or wait for new payments, top up your reserve, or reduce the refund amount and try again. Contact support if the issue persists. |
| refund_cannot_be_initiated _due_to_insufficient_balance |
This error occurs when your Zoho Payments account balance is insufficient while attempting to initiate a refund. | Ensure your account has sufficient balance, or wait for new payments, top up your reserve, or reduce the refund amount and try again. Contact support if the issue persists. |
| payment_authentication_failed | This error occurs when the authentication process for the payment method has failed. | Ensure that the customer has completed all required authentication steps, then retry the payment. |
| payment_not_authenticated | This error occurs when the payment method fails authentication checks. | Verify the authentication details (card details, OTP, ZIP, etc.) and retry the payment. |
| payment_authentication _incomplete |
This error occurs when the payment method’s authentication process is incomplete. | Ensure the authentication process is completed and retry the payment. |
| card_authentication_error | This error occurs when the card details cannot be verified or authenticated. | Verify the authenticity of card details and retry the payment. |
| payment_authentication_timeout | This error occurs when the authentication process takes too long and exceeds the allowed time limit. | Retry the payment and complete it within the allowed time frame. |
| card_declined_by_issuer | This error occurs when the card issuer rejects the transaction for various reasons, such as expired card details, or suspected fraud. | Request the customer to contact their card issuer for more information or retry the payment using a different payment method. |
| generic_decline | This error occurs when the payment is rejected without a specific reason for decline. | The reason is unknown. Request the customer to contact their card issuer for more details. |
| lost_or_stolen_card | This error occurs when the card issuer blocks transactions for cards flagged as lost or stolen. | Request the customer to contact their card issuer to report the transaction and try the payment again. |
| incorrect_card_details | This error occurs when the card number, expiration date, or CVV does not match the issuer’s records. | Ensure the card details (number, expiry date, CVV) are correctly entered. |
| request_not_valid | This error occurs when the request is invalid or missing required fields. | Ensure the API request follows the required API parameters and try again. |
| insufficient_funds | This error occurs when the account lacks sufficient funds to cover the transaction amount. | Ensure the account has enough funds to complete the transaction. |
| expired_card | This error occurs when the card’s expiration date is past the current date. | Request the customer to use a different payment method or another valid card for the transaction. |
| card_velocity_exceeded | This error occurs when the transaction is declined because the card has exceeded its allowed transaction frequency or limit. | Verify the card details and ask the customer to contact their card issuer to check the transaction limits or request an upgrade to the card’s limits. |
| fraudulent | This error occurs when the issuing bank detects patterns or data suggesting potential fraud and notifies us. | Request the customer to retry the payment using a different payment method. |
| card_decline_rate_limit_exceeded | This error occurs when the card is declined too many times in a short period, surpassing the allowed decline rate. | Wait and try again later to avoid exceeding the decline rate limit. |
| payment_cannot_be_processed | This error occurs when the payment cannot be processed due to unforeseen issues, such as network failures or invalid payment details. | Retry the transaction again later. If the issue persists, contact support@zohopay.com |
| reenter_transaction | This error occurs when a payment fails due to an unknown issue. | Request the customer to re-enter the transaction details to proceed. |
| issuer_not_available | This error occurs when the payment could not be processed because the card issuer could not be reached to authorise the payment. | Retry the transaction later when the card issuer becomes available for authorisation or use another payment method. |
| duplicate_transaction | This error occurs when a similar payment was recently processed using the same card details | Verify the transaction ID and payment details used. Retry the transaction if required. |
| customer_authentication_required | This error occurs when the payment cannot be processed because customer authentication is required to complete the transaction. | Request the customer to complete the authentication process (e.g., OTP verification) to process the payment. |
| invalid_card_details | This error may occur if the card number, CVV, or expiration date provided is incorrect. | Verify the card details (number, CVV, expiration date) and retry the payment. |
| declined_by_customer | This error occurs when the customer decides to abort the transaction. | No further action is needed as the customer chose to abort the transaction. |
| payment_attempt_failed | This error occurs when the acquiring bank or payment processor declines the payment request. | Request the customer to retry the payment using a different payment method or contact support@zohopay for more details. |
| insufficient_customer_details | This error occurs when required customer information is missing or incomplete. | Request the customer to verify if the required information is provided before retrying. |
| customer_max_payment_methods | The customer has reached the maximum number of payment methods allowed (100). | Request the customer to remove unused or expired payment methods and try again. |
| invalid_payment_method_usage | This error occurs when the payment method is not valid for the type of transaction being attempted. | Request the customer to verify that the payment method is appropriate for the intended transaction type. |
| payment_method_not _associated_to_customer |
The payment method is not linked to the customer’s profile. | Associate a valid payment method to the customer and try again. |
| payment_method_unactivated | This error occurs when the payment method has not been activated. | Ensure the setup and verification process for the payment method is complete, or try using a different payment method. |
| payment_method_type _not_supported |
The selected payment method type is not supported. | Request the customer to use a different payment method to complete the transaction. |
| payment_method_expired _for_authorization |
This error occurs when the payment method’s expiration date has passed. | Request the customer to use a different payment method to complete the transaction or initiate a new transaction. |
| payment_method_cannot _be_updated |
This error occurs when the payment method details cannot be modified because it wasn’t successfully added. | Retry adding the payment method or ask the customer to use a different payment method. If the issue persists, contact support@zohopay.com for assistance. |
| payment_not_authorized | This error occurs when the payment is not authorized, and cannot be completed successfully. | Request the customer to complete the authorization process for the payment. |
| payment_authorization_stopped | This error occurs when the payment authorization is interrupted or canceled before it is completed. | Ensure payment authorization is complete. If canceled, ask the customer to retry the payment and complete the authorization. |
| payment_method_unverified | This error occurs when the payment method details have not been confirmed or validated. | Request the customer to use a different payment method and try again. |
| incorrect_bank_account_details | This error occurs when the bank account details provided are incorrect or invalid. | Ensure that the bank account number, routing number, and other bank account information are entered correctly, then try again. |
| bank_account_declined | This error occurs when the bank rejects the transaction. | Request the customer to contact their bank or use a different payment method. |
| bank_account_exists | This error occurs when attempting to add a bank account that is already registered under another customer. | Request the customer to provide a different bank account. |
| bank_account_unusable | This error occurs when the bank account cannot be used for the transaction because it does not support ACH payments. | Request the customer to use a different bank account or payment method for the transaction. |
| bank_account_closed | The bank account is no longer active or has been closed. | Request the customer to provide a valid, active account. |
| bank_account_frozen | The bank account has been frozen by the issuing bank due to regulatory or legal reasons. | Request the customer to resolve the issue with their bank or provide an alternative account. |
| payment_attempt_expired | This error occurs when the payment attempt times out due to the customer not completing the payment within the allowed time frame. | Request the customer to retry the payment and ensure it is completed within the specified time limit. |
| payment_method_cannot _be_deleted |
This error occurs when the payment method cannot be removed, typically because it is linked to an ongoing transaction. | Ensure the payment method is not associated with any active transactions and try again. |
| payment_method_cannot _be_saved |
This error occurs when the payment method cannot be saved for future transactions. | Request the customer to use the payment method for one-time payments. |
| payment_method_details _not_associated_to_customer |
This error occurs when the provided payment method details are not linked to the customer. | Verify the details provided and try again. If the issue persists, contact support@zohopay.com for assistance. |
| invalid_payment_method _type_for_update |
This error occurs when the provided payment method type does not match the existing one associated with the customer. | Ensure that the payment method type used in the update matches the existing one. |
Connectivity Errors
These are low-level errors that arise due to problems with network connectivity like socket timeouts. Some examples include the client prematurely terminating a call to Zoho Payments before receiving a response or timing out while reading the response due to slow connectivity or short timeout settings.
These are typically temporary errors which resolve on retry. However, persistent occurrences point to a network problem that needs to be fixed.
| Error Code | Description | Solution |
|---|---|---|
| request_time_out | This error occurs when the request takes too long to complete, leading to the expiration of the session. | Request the customer to retry the request after some time or check for any network issues before retrying. |
| unable_to_connect | This error occurs while processing the request, possibly due to network or connectivity issues. | Request the customer to check their network connection and retry. If the issue persists, review the payment details and contact support@zohopay.com. |
Rate Limit Errors
Rate limit errors occur when your integration sends too many requests in a short period. Once the rate limit is exceeded, further requests will be temporarily blocked, and an error response with HTTP status code 429 will be returned.
| Error | HTTP Status Code | Solution |
|---|---|---|
| Rate Limit Exceeded | 429 | - Wait for a while and try again. - Introduce delays between API calls to handle this automatically. - For a higher rate limit, contact us at support@zohopay.com. |
Authentication Errors
These errors occur when authentication fails due to invalid OAuth credentials.
| Error | HTTP Status Code | Solution |
|---|---|---|
| Authentication Errors | 401 | - Ensure the OAuth credentials in your code are correct. - Regenerate and use the updated OAuth credentials if invalid. |
