List of BBPS Errors

List of BBPS bill payment errors with descriptions and next steps, organised by API step.

Available in🇮🇳 India

Below are the error reasons returned by Razorpay’s Bill Payments (BBPS) APIs, organised by the API step where each error occurs. Errors are surfaced either in the response body (synchronous failures) or in the error_* fields of the Fetch Bill Request and Fetch Bill Payment responses (asynchronous failures).

Error Structure

A BBPS error response contains code, description, source, step, reason and metadata parameters.

Sample Error Response

{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "The customer account details provided are incorrect or do not match the biller's records. Verify the account identifier and retry.",
    "source": "customer",
    "step": "bill_request",
    "reason": "invalid_customer_details",
    "metadata": {}
  }
}

Parameter	Description
code	The high-level HTTP error class. Possible values are BAD_REQUEST_ERROR, GATEWAY_ERROR or SERVER_ERROR.
source	The failure origin. Possible values are customer, biller, gateway, business or internal.
step	The API stage where the failure occurred. Possible values are bill_request, bill_payment, biller_info_fetch, biller_plan_fetch or internal.
reason	Machine-readable identifier you can use for programmatic error handling.

Bill Request Errors

Errors returned by Create a Bill Request and Fetch Bill Request (step: bill_request).

Bad Request Errors

Error Reason	Detailed Error Description	Next Steps
aadhaar_not_linked	The customer’s Aadhaar number is not linked with their account at the biller.	The customer must link their Aadhaar with the biller before this transaction can proceed.
bill_already_paid	The bill for this period has already been paid. No outstanding amount is due for this customer account.	Inform the customer that no payment is required for the current cycle.
bill_expired	The bill’s due date has expired and the biller is no longer providing bill details for this period.	Direct the customer to contact the biller for the latest outstanding amount. Re-fetch the bill using a new bill request.
biller_not_found	The biller id provided does not correspond to a valid or active biller.	Verify the biller_id or gateway_biller_id and use one returned by the Fetch Billers API.
booking_already_pending	A booking is already pending for this customer account at the biller.	Wait for the existing booking to complete before initiating a new one.
channel_not_permitted	Payments are not permitted for this customer account via the current channel.	The customer must use a supported channel or contact the biller to enable collection on the current channel.
customer_account_blocked	The customer’s account with this biller is blocked, closed or suspended.	The customer must contact the biller to resolve their account status.
customer_account_deactivated	The customer’s account with the biller has been deactivated. A specific reactivation payment may be required.	Direct the customer to contact the biller for reactivation instructions.
customer_account_not_activated	The customer’s account has not been activated with this biller.	The customer must complete account activation with the biller before bill payments can be made.
customer_migrated_to_different_biller	The customer’s account has been migrated to a different distribution company or operator.	Select the updated biller corresponding to the customer’s current provider and retry.
customer_not_found	The customer identifier (consumer id, LPG id, VRN and so on.) was not found in the biller’s system.	Verify the identifier format and value, then retry.
duplicate_request	A request with the same idempotency key or reference identifiers has already been processed.	Poll the Fetch Bill Request API for the original transaction. Do not retry with the same idempotency key.
duplicate_transaction	A bill transaction is already in progress for this customer account.	Wait for the current transaction to reach a terminal status before initiating a new one.
epayment_not_enabled	Online or electronic payment is not enabled for this customer account or dealer at the biller.	The customer must contact the biller to enable ePayment for their account.
fetch_not_supported	Bill fetch is not supported by this biller. Only direct pay is permitted.	Skip the Create a Bill Request step and call Create a Bill Payment directly with biller_data.account_holder and device fields.
incomplete_customer_profile	The customer’s profile in the biller’s system is incomplete.	The customer must update their profile with the biller before this transaction can proceed.
invalid_amount	The amount returned by the biller is invalid during validation.	Re-fetch the bill to get the correct payable amount.
invalid_biller	The selected biller or sub-biller is not valid for the bill being presented.	Verify the correct biller configuration and retry.
invalid_customer_details	The customer account details provided are incorrect or do not match the biller’s records.	Verify the account identifier (account number, mobile number, consumer id and so on.) and retry.
invalid_customer_email	The customer email address format is invalid.	Provide a valid email address in customer.email.
invalid_customer_info	The customer details (name, PAN, Aadhaar and so on.) provided are invalid.	Validate the customer fields and retry.
invalid_customer_mobile	The customer mobile number is invalid. Must be a 10-digit numeric value not starting with zero.	Pass a valid 10-digit mobile number in customer.mobile.
invalid_customer_params	The combination of customer parameters in biller_data.account_holder is not valid for this biller.	Pass values that match the biller’s account_holder_config.params validation rules (data_type, length, regex).
invalid_device_app	The device.app value is invalid because it exceeds length or fails the alphanumeric check.	Pass an alphanumeric value of maximum 20 characters.
invalid_device_geocode	The device.geocode value is invalid.	Provide latitude and longitude in lat,long format with at least 4 decimal places.
invalid_device_info	One or more device fields are invalid for the chosen initiating_channel.	Check the device requirements for the initiating channel and correct the field.
invalid_device_ip	The device.ip value is not a valid IPv4 or IPv6 address.	Pass a valid IP address.
invalid_device_mac	The device.mac value is not a valid MAC address.	Provide a valid MAC address (for example, 00-0D-60-07-2A-F0).
invalid_device_mobile	The device.mobile value is invalid. Must be 10-digit numeric, not starting with zero.	Pass a valid agent mobile number.
invalid_device_os	The device.os value is invalid because it exceeds length or fails the alphanumeric check.	Pass an alphanumeric value of maximum 20 characters.
invalid_initiating_channel	The device.initiating_channel value is invalid.	Accepted values: INT, MOB, MOBB, INTB, AGT, BNKBRNCH, BSC.
invalid_plan	The plan id provided is invalid for this biller.	Fetch the latest plans using Fetch Biller Plans and retry with a valid plan_id.
invalid_rates	The bill amount or rate returned by the biller is invalid.	Re-fetch the bill using a new bill request to get the latest valid rates.
invalid_subscriber_type	The customer is not a valid prepaid subscriber for this biller.	Verify the customer’s account type (prepaid/postpaid) and select the appropriate biller.
missing_biller_id	Both biller_id and gateway_biller_id are missing.	Pass either a valid biller_id or gateway_biller_id from the Fetch Billers API.
missing_customer_info	A required customer field (name, value or parameter name) is missing.	Include all mandatory customer.* fields.
missing_customer_mobile	The customer mobile number is missing.	Pass customer.mobile. This is required on every bill request.
missing_customer_params	A required customer parameter is missing.	Check the biller’s account_holder_config.params for mandatory fields and include them in biller_data.account_holder.
missing_device_app	device.app is required for MOB and MOBB channels.	Include the application name.
missing_device_geocode	device.geocode is required for INT, MOB, BNKBRNCH, AGT, BSC channels.	Include geocode in lat,long format.
missing_device_imei	IMEI is required in device information for this channel.	Contact Razorpay support.
missing_device_info	One or more required device fields are missing for the chosen initiating_channel.	Include all device fields required for the channel.
missing_device_ip	device.ip is required for INT, INTB, MOB, MOBB channels.	Include the IP address.
missing_device_mac	device.mac is required for INT, INTB channels.	Include the MAC address.
missing_device_mobile	device.mobile is required for BNKBRNCH, AGT, BSC channels.	Include the agent mobile number.
missing_device_os	device.os is required for MOB, MOBB channels.	Include the operating system.
no_outstanding_bill	No bill is currently available for this customer account.	The customer may have no outstanding dues or the bill for this cycle has not yet been generated.
payment_channel_restriction	Payment via this channel is restricted for this customer.	Direct the customer to use the channel mandated by the biller (for example, the Airtel Thanks app for Airtel Black subscribers).
payment_not_permitted	Payment is not permitted via this channel for this customer account.	The customer must contact the biller to enable collection on this channel.
plan_not_applicable	The selected plan is not applicable for this customer’s current subscription.	Select a plan compatible with the customer’s profile.
plan_not_found	The plan id was not found for the selected biller.	Re-fetch the latest plans and retry with a valid plan_id.
refill_booking_restriction	A new refill booking cannot be placed at this time.	The biller has a minimum waiting period between refills for this customer.
validation_not_supported	This biller does not support the bill validation step.	Skip validation if the biller’s bill_request_config.bill_request_required is not_supported.

Gateway Errors

Error Reason	Detailed Error Description	Next Steps
biller_scheduled_downtime	The biller is undergoing scheduled maintenance and bill fetch is temporarily unavailable.	Retry after the maintenance window.
biller_system_error	The biller’s system encountered an unexpected error or timed out processing the bill fetch.	Retry after a short interval. If the issue persists, contact Razorpay support.
biller_unscheduled_downtime	The biller’s service is temporarily unavailable due to an unplanned outage.	Retry after some time. If the issue persists, contact Razorpay support.
incomplete_biller_response	The biller’s response was incomplete or malformed during bill fetch.	This is a biller-side issue. Retry after some time or contact Razorpay support.
institution_not_active	The originating institution is not active or has been deactivated at NPCI.	Contact Razorpay support.
invalid_institution	The originating institution configuration is invalid at NPCI.	Contact Razorpay support.
no_outstanding_bill	The biller validated the account but returned no outstanding amount.	The customer may have no dues. Retry on the next billing cycle.

Bill Payment Errors

Errors returned by Create a Bill Payment and Fetch Bill Payment (step: bill_payment).

Bad Request Errors

Error Reason	Detailed Error Description	Next Steps
aadhaar_not_linked	The customer’s Aadhaar is not linked to their account with this biller.	The customer must link their Aadhaar with the biller before this payment can proceed.
adhoc_payment_not_supported	The biller does not accept direct payments without a prior bill fetch.	Call Create a Bill Request first and pass the returned bill_request_id.
amount_out_of_range	The payment amount is outside the allowed range for the chosen payment method or channel.	Check the biller’s payment_config.methods[].min_limit, max_limit and channels[] configuration. Retry with an amount within the limits.
bill_expired	The bill details used for payment are stale or the due date has expired.	Re-fetch the bill using a new bill request and retry the payment with the updated bill details.
bill_request_not_successful	The referenced bill request was not successful, so the payment cannot be initiated against it.	Wait for the bill request status to reach success before calling Create a Bill Payment.
bill_request_required	This biller requires a successful bill request before a payment can be initiated.	Call Create a Bill Request first and pass the returned bill_request_id.
bill_response_mismatch	The bill details in the payment request do not match the fetched bill response.	Pass the same bill_number and amount returned by the Fetch Bill Request API.
biller_fee_mismatch	The Customer Convenience Fee (CCF1) value in the payment request does not match the value returned in the bill request response.	Pass fees.biller_convenience_fee exactly as returned in the fetched bill’s fee details.
customer_account_blocked	The customer’s account with this biller is blocked or closed. Bill payment failed.	The customer must contact the biller to resolve their account status.
customer_account_not_activated	The customer’s account is not activated with this biller. Bill payment failed.	The customer must complete account activation with the biller before retrying.
customer_migrated_to_different_biller	The customer’s account has been migrated to a different provider.	Select the correct biller for the customer’s current provider and retry.
daily_limit_exceeded	The daily payment limit for this customer account has been exceeded at the biller.	The customer should retry the next business day.
duplicate_payment_method	The same payment method is included more than once in the payments array.	Combine the split amounts into a single payment object per method.
duplicate_request	A request with the same idempotency key has already been processed.	Poll the Fetch Bill Payment API for the original transaction. Do not retry with the same idempotency key.
duplicate_transaction	This payment has already been submitted or processed for this bill.	Poll the Fetch Bill Payment API for the original transaction status.
invalid_biller_fee	The biller fee (CCF1) provided does not match the biller’s configured fee schedule.	Fetch the latest biller configuration via Fetch Billers and use the correct CCF value.
invalid_bill_details	The bill details (bills[]) sent in the payment request are invalid.	Pass the bill details exactly as returned by the Fetch Bill Request API.
invalid_customer_details	The customer account details are incorrect or invalid at the biller. Bill payment failed.	Re-fetch the bill with corrected customer details and retry.
invalid_customer_params	The combination of customer parameters sent to the biller is not valid. Bill payment failed.	Pass values matching the biller’s account_holder_config.params validation rules.
invalid_payment_amount	The bill_pay_amount is invalid for this biller.	The amount must satisfy the biller’s payment_config.amount_exactness rule. Re-fetch the bill and use the returned amount.
invalid_payment_card	The card details in payment information are invalid.	Ensure payments[].card.last4 contains the last 4 digits and auth_code is hardcoded to Card.
invalid_payment_ifsc	The IFSC code in payment information is invalid.	Provide a valid IFSC code for netbanking payments.
invalid_payment_info	A field in the payments[] object is invalid.	Verify the method-specific sub-object matches the method value.
invalid_payment_method	The payment method passed is not valid.	Supported values: card, upi, netbanking, wallet.
invalid_payment_mobile	The mobile number in payment information is invalid.	Ensure it is a 10-digit number not starting with zero.
invalid_payment_vpa	The UPI VPA (Virtual Payment Address) is invalid.	Provide a valid VPA in payments[].upi.vpa.
kyc_limit_breached	The payment was blocked because the customer’s KYC-linked transaction limit has been exceeded with this biller.	Direct the customer to update their KYC with the biller.
missing_bill_details	The bills[] array is missing from the bill payment request.	Pass the bills returned in the Fetch Bill Request response.
missing_payment_info	The payments[] array or one of its required fields is missing.	Include the payments array with all mandatory fields.
missing_payment_method	A required payment method field is missing.	Include payments[].method and its method-specific sub-object.
payment_info_mode_mismatch	The payment information fields do not match the selected payment method.	Verify the method-specific sub-object (card, upi, netbanking, wallet) matches payments[].method.
unsupported_payment_channel	The initiating channel used is not supported by this biller.	Verify the biller’s supported channels in payment_config.channels[] and retry using a supported channel.
unsupported_payment_method	The payment method used is not supported by this biller.	Check the biller’s payment_config.methods[] and retry with a supported method.
validation_not_supported	This biller does not support direct pay without validation.	Call Create a Bill Request first and use the returned bill_request_id when initiating payment.

Gateway Errors

Error Reason	Detailed Error Description	Next Steps
biller_fee_validation_error	An error occurred while validating the convenience fee with NPCI.	Retry after some time. If the issue persists, contact Razorpay support.
biller_not_accepting_payments	The biller is temporarily not accepting payments.	Retry after some time.
biller_scheduled_downtime	The biller is undergoing scheduled maintenance and cannot accept payments.	Retry after the maintenance window.
biller_unscheduled_downtime	The biller’s service is temporarily unavailable due to an unplanned outage.	Retry after some time. If the issue persists, contact Razorpay support.
bou_pending_timeout	The bill payment request is pending at the Biller OU.	Poll Fetch Bill Payment until the status reaches success or failed. Do not retry the payment until the status is terminal.
bou_send_failed	The bill payment request failed to reach the Biller OU due to a temporary system issue.	Retry after some time.
bou_timeout	The bill payment request timed out at the Biller OU.	Retry after some time.
bou_unavailable	The Biller OU is temporarily unavailable.	Retry after some time.
incomplete_biller_response	The biller’s response was incomplete or malformed during payment processing.	This is a biller-side issue. Retry after some time or contact Razorpay support.
npci_timeout	The bill payment timed out at NPCI.	Poll Fetch Bill Payment until the status reaches success or failed. Do not retry until the terminal state.
velocity_amount_exceeded	The biller-level velocity check failed because the cumulative payment amount has exceeded the allowed threshold.	Retry after some time or contact Razorpay support.
velocity_count_exceeded	The biller-level velocity check failed because the transaction count has exceeded the allowed threshold.	Retry after some time or contact Razorpay support.
velocity_limit_exceeded	The biller-level velocity check failed because both amount and count thresholds have been exceeded.	Retry after some time or contact Razorpay support.

Biller Catalogue Errors

Errors returned by Fetch Billers and Fetch Biller Categories (step: biller_info_fetch).

Bad Request Errors

Error Reason	Detailed Error Description	Next Steps
biller_not_found	No biller was found matching the provided biller_id or gateway_biller_id.	Verify the identifier is correct and that the biller is active.
invalid_biller_filter	One or more filter values used to search billers are invalid.	Verify the filter parameters and retry.
invalid_biller_id	The biller_id provided is not in a valid format.	Pass a valid Razorpay biller id from the Fetch Billers API.
invalid_category	The category value provided is not a recognised BBPS biller category.	Use a valid BBPS category. Refer to the Fetch Billers API documentation for accepted values.
invalid_country_code	The country code provided is not valid. Only IN is supported currently.	Pass IN for geo_coverage.country.
invalid_filter_params	The filter parameters passed are invalid (for example, updated_since is a future timestamp).	Verify filter values and retry.
invalid_gateway_biller_id	The gateway_biller_id is not in a valid format. BBPS biller ids must be alphanumeric and exactly 14 characters.	Verify the value and retry.
invalid_pagination_params	The count or skip parameter is invalid.	Set count between 1 and 100 and skip to a non-negative integer.
invalid_state_code	The state code is not a valid ISO state code.	Use a valid two-letter state code (for example, MH, DL, KA).
no_results_for_filters	No billers match the combination of filters provided (category, state, status and so on.).	Broaden or remove some filters and retry.

Biller Plan Errors

Errors returned by Fetch Biller Plans (step: biller_plan_fetch).

Bad Request Errors

Error Reason	Detailed Error Description	Next Steps
invalid_biller_id	The biller_id provided is not in a valid format.	Pass a valid Razorpay biller id from the Fetch Billers API.
invalid_filter_params	The filter parameters are invalid (for example, updated_since is a future timestamp).	Verify filter values and retry.
invalid_gateway_biller_id	The gateway_biller_id is not valid. BBPS biller ids must be alphanumeric and exactly 14 characters.	Verify the value and retry.
invalid_pagination_params	The count or skip parameter is invalid.	Set count between 1 and 100 and skip to a non-negative integer.
invalid_plan_id	One or more plan_id values are not in a valid format.	Pass valid Razorpay plan ids from Fetch Biller Plans.
no_active_plans	No active plans are currently available for the specified biller.	Plans may be temporarily deactivated. Retry later or check the biller’s plan availability.
no_results_for_filters	No plans match the combination of filters provided.	Broaden or remove some filters and retry.
plan_not_found	The plan_id was not found for the specified biller.	Re-fetch the latest plans and use a valid plan_id.
plans_not_supported	The biller does not offer plans. Plans are only available for prepaid billers (mobile, DTH, OTT).	Skip the plan fetch step for postpaid billers.

Internal Errors

Razorpay-side errors that are not caused by the merchant’s request (step: internal). These map to HTTP 500 or 502 depending on the failure type.

Error Reason	Detailed Error Description	Next Steps
internal_error	A technical error occurred on Razorpay’s end while processing the request.	Retry after some time. If the issue persists, contact Razorpay support with the request reference id.
invalid_request_format	The request failed protocol-level validation at Razorpay’s BBPS layer (header, transaction block, risk score or signature).	These are internal validation errors. Contact Razorpay support with the request reference id.