> ## Documentation Index > Fetch the complete documentation index at: https://razorpay-881012b3.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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)](/docs/api/bills/bill-payments) 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. ```json Sample Error Response theme={null} { "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](/docs/api/bills/bill-payments/create-bill-request) and [Fetch Bill Request](/docs/api/bills/bill-payments/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](/docs/api/bills/bill-payments/create-bill-payment) and [Fetch Bill Payment](/docs/api/bills/bill-payments/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](/docs/api/bills/bill-payments/fetch-billers) and [Fetch Biller Categories](/docs/api/bills/bill-payments/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](/docs/api/bills/bill-payments/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. |