This section will help you debug any errors that you might get when working on the integration.


Try our Integration

Error handling

For any API related action, please ensure that only a 200 response is treated as a successful action. Any non 200 response should be treated as failure. If there is some error in your request, you will receive a 4xx response with the following error json.

{ "message": "return_url : return_url must contain {order_id} and {order_token}", "code": "return_url_value_invalid", "type": "invalid_request_error" }

Every error json contains three parts - type, code and a message.
The type tells you what kind of error you have faced. The code and message go into the details of the error and tell you exactly what is wrong.

Tracing errors

Every response from Cashfree API will contain the following parameters in the response headers. The response headers should help you with the x-request-id. This is a unique identifier for every api call in Cashfree's system. If you want us to debug any API call, please share the this value with our technical support team. Using this identifier, we will be able to trace your API request in our system.

The second part of the response headers also contains the ratelimiting parameter values. We rate limit every API call for every merchant account and every IP address. If you are getting a 429 response code, the headers will contain the actual values for your account (or IP) and when you again you can retry.

content-type: application/json; charset=UTF-8
content-length: 145
x-api-version: 2021-05-21
x-ratelimit-limit: 30
x-ratelimit-remaining: 29
x-ratelimit-retry: 0
x-ratelimit-type: app_id
x-request-id: 3bdf5e286a47efa99c6d182f2ab7d602

API Metrics

You can view the API Metrics from merchant dashboard. It provides you with more visibility in terms of metrics and the health of your APIs such as:

  • Error Counts
  • Latency
  • API Usage

Error Codes

The below error codes will be sent by Cashfree in case the error type is invalid_request_error.

order_amount_invalidOrder amount is invalid. You need to provide order amount in two decimals. This might also happen if your order amount is to less, or it exceeds the order limit set by cashfree.
order_amount_missingOrder amount needs to be provided
order_currency_invalidOrder currency needs to be provided
order_currency_missingOrder currency needs to be provided
customer_id_invalidCustomer ID is invalid. Please check the regex for customer ID
customer_id_missingCustomer ID needs to be provided
customer_email_invalidCustomer Email is invalid. Please provide a valid email id.
customer_email_missingCustomer Email needs to be provided
customer_phone_invalidCustomer Phone is invalid. Pleae provide a valid Indian phone number
customer_phone_missingCustomer Phone needs to be provided
order_expiry_time_invalidOrder Expiry time is invalid. Please ensure that order expiry is atleast 15 minutes from now and a maximum 30 days from now
notify_url_invalidNotify URL is invalid. It should be a valid url. You must use "https" endpoint in production
return_url_invalidReturn URL is invalid. It should be a valid url. You must use "https" endpoint in production
payment_methods_invalidPayment methods in create order call should be a valid string. It should contain specific values like "cc", "dc", etc.
order_note_invalidOrder note is invalid. Please check the regex for a valid order note
order_token_invalidOrder token is invalid.
payment_method_missingPayment method is missing in the payment request
channel_invalidChannel provided is invalid
payment_method_invalidPayment Method is invalid in the payment request
netbanking_bank_code_invalidNetbanking Code is invalid. Please check the netbanking code with specific Cashfree values
card_number_invalidCard number is invalid.
card_cvv_invalidCard CVV is invalid
card_expiry_mm_invalidCard expiry month should be in two digits.
card_expiry_yy_invalidCard expiry year should be in two digits.
card_alias_invalidCard alias provided is invalid
order_inactiveOrder is no longer ACTIVE. It has either been PAID or EXPIRED.
upi_id_invalidUPI Id provided is invalid
upi_id_missingUPI id is missing
order_not_foundOrder was not found for this request.
request_failedRequest failed. Please check with Cashfree (share the x-request-id for easier debugging)
refund_amount_invalidRefund amount is invalid. It should be less than equal to order amount less already refunded amount.
refund_id_invalidRefund id provided is invalid
refund_note_invalidRefund note is invalid. Please check the regex for refund note.
internal_errorCashfree internal error. Please check with Cashfree (share the x-request-id for easier debugging)
card_not_supportedThis card is not supported for this merchant account
payment_method_not_supportedPayment method not enabled for this merchant account.
authorize_only_invalidPre authorization parameter missing
phone_ineligiblePhone number given not eligible for payment method
order_amount_ineligibleOrder amount given not eligible for payment method

Ask a question about Integration

You can ask questions, and participate in discussions about Cashfree PG API in the Cashfree Discord channel.