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 | Unauthorised (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."
}
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 Errors
Payment errors occur when issues arise during payment processing. Even if your integration is functioning correctly, the processor or issuer may decline the payment due to conditions or checks on their end.
| 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 other than INR. Using other currencies will trigger this error. | Request the customer to use INR as the payment currency, as other currencies are not supported. |
| 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 and that the refund amount is valid. |
| 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@zohopayments.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 attempting to issue a refund while a dispute is ongoing. | You should wait until the dispute is resolved before attempting a refund. |
| payment_not_captured | This error occurs when attempting to perform actions on a payment that has not been finalised or completed. | You should wait until the transaction is completed before performing any actions. |
| 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 the refund amount does not exceed the available account balance. |
| 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 funds to process the refund. |
| payment_authentication_failed | This error occurs when the authentication process for the payment method does not succeed. | Verify the authentication details and retry the payment. |
| payment_not_authenticated | This error occurs when the payment method fails authentication checks. | Verify the authentication details (card details, OTP, billing address, 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 does not meet the API’s requirements. | Ensure the API request follows the required API parameters. |
| 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@zohopayments.com |
| reenter_transaction | This error occurs when a payment fails due to an unknown issue. Please re-enter the transaction details to proceed. | Ensure the session is active, complete the payment process, or re-enter payment details before retrying the transaction. |
| 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. |
| 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 fails or cannot be processed because customer authentication is required to complete the payment. | Complete the customer 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. |
| transaction_failed | The payment failed while processing. | Verify the payment details and payment method, then retry the transaction. If the issue persists, contact support@zohopayments.com |
| bank_declined | This error occurs when the bank rejects the payment. | Request the customer to contact their bank for more clarification. |
| bank_blocked | This error occurs when the bank blocks the payment from being processed. | Request the customer to contact their bank to check the payment issue and request them to approve the transaction, if required. |
| 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. |
| net_banking_transaction_ declined_unknown_reason |
This error occurs when the bank rejects the payment without providing a specific reason for the decline. | Reach out to the bank to find out why the transaction was declined. |
| 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. |
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@zohopayments.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@zohopayments.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. |
