Skip to main content

​
Error structure

The Payment Gateway response in case of an error includes the following:
  • error_code - Code associated with every error.
  • error_description - Description of the error.
  • error_source - Source of the error.
  • error_reason - Failure reason.
Sample error response from API: 
{
  "message": "bad URL, please check API documentation",
  "help": "Check latest errors and resolution from Merchant Dashboard API logs: https://bit.ly/4glEd0W Help Document: https://bit.ly/4eeZYO9",
  "code": "request_failed",
  "type": "invalid_request_error"
}
Sample error response from webhook: 
{
    "auth_id": null,
    "authorization": null,
    "bank_reference": "306118259130",
    "cf_payment_id": 1636676360,
    "entity": "payment",
    "error_details": {
        "error_code": "TRANSACTION_DECLINED",
        "error_description": "transaction is rejected at the remitter bank end. Please reach out to issuer bank",
        "error_reason": "bank_rejected",
        "error_source": "bank"
    },
    "is_captured": false,
    "order_amount": 1.00,
    "order_id": "order_18482MSWq8prPMOW0jTeGsx0B1JmPC1",
    "payment_amount": 1.00,
    "payment_completion_time": "2023-03-02T18:24:51+05:30",
    "payment_currency": "INR",
    "payment_group": "upi",
    "payment_message": "01::REJECTED",
    "payment_method": {
        "upi": {
            "channel": "collect",
            "upi_id": "8XXXXXXXX2@upi"
        }
    },
    "payment_status": "FAILED",
    "payment_time": "2023-03-02T18:24:18+05:30"
}

​
List of error types and error codes

Below are the error types and error codes with their descriptions.

​
Error types

error_typedescription
api_connection_errorNetwork communication issue with API server.
api_errorGeneral server error during request processing.
authentication_errorInvalid or missing authentication credentials.
invalid_request_errorRequest is malformed or has invalid parameters.
feature_not_enabledRequested feature is not enabled for the account.
rate_limit_errorToo many requests sent in a short time.
validation_errorRequest failed validation checks.
idempotency_errorRepeated request with same idempotency key caused conflict.
bad_gateway_errorReceived invalid response from upstream server.

​
Error codes

error_codedescription
card_unsupportedCard type not supported by payment system.
payment_method_unsupportedPayment method not accepted for this transaction.
surcharge_invalidSurcharge amount is missing, incorrect, or not allowed.
payment_gateway_unsupportedSelected payment gateway is not supported.
card_submission_disabledCard submission is currently disabled or blocked.
order_amount_invalidOrder amount is missing, negative, or exceeds limits.
order_inactiveOrder is no longer active or has expired.
customer_email_invalidCustomer email is missing or incorrectly formatted.
version_invalidProvided API version is not supported or malformed.
order_token_invalidOrder token is missing, expired, or incorrect.
sub_session_id_invalidSub-session ID is missing or invalid.
payment_session_id_invalidPayment session ID is missing or does not exist.
native_otp_session_id_invalidNative OTP session ID is invalid or expired.
flash_upi_auth_token_invalidFlash UPI auth token is invalid or expired.
cookie_invalidSession cookie is missing, expired, or malformed.
order_id_invalidOrder ID is incorrect, missing, or unrecognised.
order_expiry_time_invalidOrder expiry time is missing, invalid, or in past.
order_id_not_paidOrder ID exists, but payment was not completed.
order_id_voidedOrder was voided and cannot be processed further.
refund_amount_invalidRefund amount is missing, invalid, or exceeds original payment.
refund_id_invalidRefund ID is missing, incorrect, or unrecognised.
netbanking_bank_code_invalidInvalid or unsupported netbanking bank code provided.
payment_method_invalidSpecified payment method is invalid or not recognised.
refund_invalidRefund cannot be processed due to invalid conditions.
vendor_id_invalidVendor ID is missing, malformed, or not recognised.
payment_gateway_inactivePayment gateway is inactive or unavailable.
customer_phone_invalidCustomer phone number is missing or incorrectly formatted.
partner_apikey_invalidPartner API key is missing, invalid, or unauthorised.
payment_amount_invalidPayment amount is missing, negative, or incorrectly formatted.
refund_unsupportedRefund operation is unsupported for this payment type.
order_already_paidOrder has already been paid successfully.
bank_processing_failureBank failed to process the payment request.
api_request_timeoutAPI request timed out before completion.
sdk_token_invalidSDK token is invalid or malformed.
sdk_token_unknownUnknown SDK token provided in the request.
simulation_id_invalidSimulation ID is invalid or does not exist.
entity_id_invalidEntity ID is incorrect, missing, or unrecognised.
entity_unsupportedEntity type is not supported for this operation.
simulation_id_missingSimulation ID is required but missing in request.
subscription_id_missingSubscription ID is required but missing.
payment_id_missingPayment ID is missing or not found.
plan_id_missingPlan ID is missing, invalid, or not found.
refund_id_missingRefund ID is required but missing.
PaymentForm_form_creation_failedFailed to create payment form due to internal error.
PaymentForm_link_creation_failedFailed to create payment link due to system issue.
order_already_existsOrder already exists with the given ID or details.
orderpay_already_existsOrderPay object already exists for this order.
order_id_already_existsOrder ID already exists and cannot be duplicated.
domain_name_refererStringInvalid or unapproved domain name in referer header.
android_package_{xRequestedWith}Invalid or unrecognised Android package name in request.
refType_not_approvedReferenced entity is not approved for this operation.
refType_ineligibleReferenced entity is not eligible for this operation.
payment_gateway_inactive_request_failedPayment gateway inactive; request could not be completed.
subscription_id_missing_request_failed_failedSubscription ID missing; request failed.
simulation_id_missing_request_failed_failedSimulation ID missing; request failed.
cod_eligibility_failedCOD eligibility check failed for this order.
Paymentlink_create_failedFailed to create payment link due to internal issue.
headless_otp_submit_request_failedOTP submission failed during headless authentication flow.
order_creation_faiedOrder creation failed due to validation or server error.
pan_submit_failedPAN submission failed due to invalid data or server error.
gstin_submit_failedGSTIN submission failed due to incorrect or missing data.
cin_submit_failedCIN submission failed due to invalid or missing data.
risk_data_ip_address_request_failedIP address risk check failed during request processing.
cart_create_failedCart creation failed due to invalid input or server issue.
order_create_failedOrder creation failed; please retry or check input data.
order_pay_failedOrder payment attempt failed due to processing error.
refund_post_failedRefund request failed to post due to system error.
link_post_failedFailed to post link request to server.
api_request_failedAPI request failed due to timeout or internal error.
form_post_failedForm submission failed due to validation or processing error.
aadhar_otp_generation_failedAadhaar OTP generation failed during identity verification.
aadhar_otp_verification_failedAadhaar OTP verification failed or expired.
pan_verification_failedPAN verification failed due to a mismatch or system error.
bank_account_verification_failedBank account verification failed due to invalid input.
otp_generation_failedOTP generation failed due to rate limits or server error.
otp_expired_failedOTP has expired; please request a new one.
otp_invalid_failedOTP is invalid or does not match.
ref_id_invalid_failedReference ID is invalid or not found.
shipping_fetch_failedShipping info fetch failed due to network or service error.
entity_simulation_payment_error_code_failedEntity simulation failed during payment processing.
gst_verification_failedGST verification failed due to incorrect or unverified GSTIN.
offer_not_foundOffer not found or does not exist.
customer_get_not_foundCustomer not found with given details.
payment_not_foundPayment record not found for provided ID.
payment_post_not_foundPayment request failed; resource not found.
entityId_not_foundEntity ID not found or unrecognised.
order_get_not_foundOrder not found for given ID.
cart_get_not_foundCart not found for current session or ID.
orderpay_post_not_foundOrderPay request not found or already processed.
card_alias_not_foundCard alias not found or invalid.
cardbin_details_not_foundCard BIN details not available or missing.
card_not_foundCard not found or does not exist.
order_id_post_not_foundOrder ID not found in post request.
modeRates_get_not_foundMode rate information not available or missing.
refund_get_not_foundRefund information not found for provided ID.
transaction_get_not_foundTransaction details not found or unavailable.
settlement_get_not_foundSettlement not found for provided identifier.
link_get_not_foundPayment link not found or deleted.
merchant_get_not_foundMerchant account not found or unregistered.
terminal_id_post_not_foundTerminal ID not found in post request.
resource_post_not_foundResource not found during post request.
terminal_post_not_foundTerminal not found or inactive.
order_request_not_foundOrder request not found or expired.
payment_request_not_foundPayment request not found or invalid.
dispute_request_not_foundDispute request not found or missing.
document_request_not_foundDocument request not found or expired.
resource_get_not_foundRequested resource not found or unavailable.
form_get_not_foundForm not found or has been removed.
authentication_errorAuthentication failed due to invalid or missing credentials.
customer_instruments_authentication_errorCustomer instruments request failed authentication.
integrity_token_not_foundIntegrity token not found or expired.
checkout_config_not_foundCheckout configuration not found or misconfigured.
api_error_not_foundAPI error: requested resource not found.
payment_instrument_not_foundPayment instrument not found or unsupported.
order_not_foundOrder does not exist or was deleted.
instrument_not_foundInstrument not found for current customer or request.
request_failedRequest failed due to server or network error.
cryptogram_request_failedCryptogram generation failed or request is invalid.
authorize_only_invalidAuthorise-only is not allowed for this transaction.
card_number_invalidCard number is invalid or incorrectly formatted.
emi_tenure_invalidEMI tenure is invalid or unsupported for selection.

​
List of errors for payments

Download the list of errors along with their explanation. Payment Error List
Error details will be shown for every failed transaction in the payload of the following APIs and webhooks: