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
API Errors
Validation Errors
Payment Errors
Connectivity Errors
Rate Limit Errors
Authentication Errors

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).
invalid_session	This error occurs when the payment session has expired, is invalid, or the associated payment has already been completed.	Create a new payment session and retry the request.

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	Description	Solution
Invalid Authorization URL	400	Triggered when the authorization URL is missing required parameters.	- Ensure all required parameters (client_id, redirect_uri, response_type, soid, scope) are included in the authorization URL. - Verify that parameters are properly encoded in the URL.
Authorization Code Expired	400	Occurs when the authorization code has expired.	- Generate a new authorization code, as authorization codes are valid for only 1 minute, and can only be used once. - Retry the request immediately after generating the new code.
Invalid Authorization Code	400	Triggered when the authorization code is expired, invalid, or already used.	- Ensure the authorization code is valid and not expired. - Do not reuse an authorization code. - Generate a new authorization code and retry.
Extra Parameter Found	400	Triggered when unexpected parameters are sent in the API request.	- Remove unsupported parameters from the API request. - Ensure the OAuth token is passed in the Authorization header and not as a request parameter.
Invalid Client ID	401	Occurs when the Client ID provided does not match any registered client application.	- Verify that the correct Client ID is used. - Ensure the client application is registered at the organization level. - Regenerate the client credentials if necessary.
Invalid Client Secret	401	Triggered when the Client Secret does not match the associated Client ID.	- Verify that the correct Client Secret is used. - Ensure it corresponds to the correct Client ID. - Regenerate the secret if required and retry.
Invalid Redirect URI	401	Occurs when the redirect URI in the request does not match the registered one.	- Ensure the redirect URI exactly matches the one registered in the developer console. - Check for mismatched protocol (HTTP/HTTPS) or trailing slashes.
Incorrect Organization ID	401	Triggered when the SOID does not match the intended organization.	- Verify that the correct Organization ID (SOID) is used. - Ensure it matches the appropriate environment (live or sandbox).
Access Forbidden	401	Access denied due to insufficient permissions or invalid token.	- Verify that the access token is valid and has sufficient permissions. - Ensure the associated user has access to the requested resource.
Invalid Code	401	Occurs when a refresh token is mistakenly used where an access token is required.	- Ensure that an access token is used when calling the API. - Do not use a refresh token in place of an access token.
Invalid OAuth Credentials	401	Occurs when OAuth credentials are invalid or incorrectly configured.	- Ensure the OAuth credentials in your code are correct. - Regenerate and use updated OAuth credentials if they are invalid.
Invalid or Insufficient Scopes	401	Triggered when the access token does not have all required scopes.	- Verify that the required API scopes were included while generating the access token. - Generate a new access token using the refresh token if the current token has expired.
Invalid Token	401	Occurs when the access token is invalid or mismatched with credentials.	- Verify that the access token is correct and matches the client credentials. - Ensure the token is being used in the correct environment.
Expired Token	401	Triggered when the access token has expired.	- Generate a new access token using the refresh token. - Ensure the new token is being used in the correct environment.
Not an Authorized User	401	This error can occur due to authentication or environment configuration issues, including: - Using an incorrect token (e.g., a ZAPI key instead of a valid OAuth access token) - Using sandbox tokens in a live environment, or live credentials in a sandbox environment - An invalid or expired access token - An access token that does not include the required scope for the specific request	- Use a valid OAuth access token that was generated. - Ensure the token has the required permissions. - Ensure a sandbox access token is used only with the sandbox domain. - Verify the SOID format is zohopaysandbox.{account_id}. - Confirm the API domain used is https://paymentssandbox.zoho.in. - Use an access token generated specifically in the sandbox environment.
Unauthorized (Expired Access Token)	401	Occurs when the access token has expired.	- Generate a new access token using the refresh token. - Replace the expired token in the API request.
Unauthorized	401	Generic unauthorized error due to invalid token, account ID, or scopes.	- Ensure the Account ID used is valid. - Verify a valid access token is used when calling the API. - If the access token has expired, generate a new one using the refresh token. - Confirm that the OAuth scopes required by the API match the scopes provided while generating the authorization code.
Not Authorized	401	Triggered when the API key or session is invalid, missing required access, or when the request URL is incorrect.	- Ensure the API key used is active. - Verify that the API key is generated from the correct developer space. - Verify the Account ID is correct. - Create a new session and retry loading the checkout widget. - Ensure the request URL is correct and matches the required environment (e.g., live vs sandbox).
Invalid Scope (Authorization Format Issue)	401	Occurs when the Authorization header is malformed or the scope format is incorrect.	- Verify the Authorization header format (e.g., Authorization: `Zoho-oauthtoken` `{access_token}`). - Ensure the scope syntax is valid and correctly structured.
Permission Denied	403	Occurs when the user does not have sufficient privileges to perform the action.	- Ensure the OAuth credentials are valid and generated by a current Admin or Account Owner. - Contact your admin to update your role and retry the request.
Invalid OAuth Scope	404	Occurs when the requested API scope is invalid or unsupported.	- Verify that valid and supported scopes are requested. - Ensure the scope format matches the API requirements. - Regenerate the authorization code with the correct scopes.
Invalid Account ID	404	Triggered when the provided Account ID does not exist or is invalid.	- Ensure the Account ID parameter is included in the request. - Verify that the Account ID is valid and belongs to the correct organization.
Not Authorized (Invalid Parameters)	202	Occurs when required parameters are missing or malformed.	- Verify that all mandatory parameters are included in the API request. - Ensure parameter names and formats match the API documentation.
Invalid Code (Missing access_type)	200K	Occurs when the access_type parameter is missing during code generation.	- Regenerate the authorization code with the correct access_type (online/offline). - Use the newly generated code to obtain access and refresh tokens.