INTEGRATION TOOLKIT

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.

Code	Description
order_amount_invalid	Order 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_missing	Order amount needs to be provided
order_currency_invalid	Order currency needs to be provided
order_currency_missing	Order currency needs to be provided
customer_id_invalid	Customer ID is invalid. Please check the regex for customer ID
customer_id_missing	Customer ID needs to be provided
customer_email_invalid	Customer Email is invalid. Please provide a valid email id.
customer_email_missing	Customer Email needs to be provided
customer_phone_invalid	Customer Phone is invalid. Pleae provide a valid Indian phone number
customer_phone_missing	Customer Phone needs to be provided
order_expiry_time_invalid	Order Expiry time is invalid. Please ensure that order expiry is atleast 15 minutes from now and a maximum 30 days from now
notify_url_invalid	Notify URL is invalid. It should be a valid url. You must use "https" endpoint in production
return_url_invalid	Return URL is invalid. It should be a valid url. You must use "https" endpoint in production
payment_methods_invalid	Payment methods in create order call should be a valid string. It should contain specific values like "cc", "dc", etc.
order_note_invalid	Order note is invalid. Please check the regex for a valid order note
order_token_invalid	Order token is invalid.
payment_method_missing	Payment method is missing in the payment request
channel_invalid	Channel provided is invalid
payment_method_invalid	Payment Method is invalid in the payment request
netbanking_bank_code_invalid	Netbanking Code is invalid. Please check the netbanking code with specific Cashfree values
card_number_invalid	Card number is invalid.
card_cvv_invalid	Card CVV is invalid
card_expiry_mm_invalid	Card expiry month should be in two digits.
card_expiry_yy_invalid	Card expiry year should be in two digits.
card_alias_invalid	Card alias provided is invalid
order_inactive	Order is no longer ACTIVE. It has either been PAID or EXPIRED.
upi_id_invalid	UPI Id provided is invalid
upi_id_missing	UPI id is missing
order_not_found	Order was not found for this request.
request_failed	Request failed. Please check with Cashfree (share the x-request-id for easier debugging)
refund_amount_invalid	Refund amount is invalid. It should be less than equal to order amount less already refunded amount.
refund_id_invalid	Refund id provided is invalid
refund_note_invalid	Refund note is invalid. Please check the regex for refund note.
internal_error	Cashfree internal error. Please check with Cashfree (share the x-request-id for easier debugging)
card_not_supported	This card is not supported for this merchant account
payment_method_not_supported	Payment method not enabled for this merchant account.
authorize_only_invalid	Pre authorization parameter missing
phone_ineligible	Phone number given not eligible for payment method
order_amount_ineligible	Order 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.