List of BBPS Errors

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.

{
  "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": {}
  }
}

Bill Request Errors

Errors returned by

Create a Bill Request

and

Fetch Bill Request

(step: bill_request).

Bad Request Errors

Gateway Errors

Bill Payment Errors

Errors returned by

Create a Bill Payment

and

Fetch Bill Payment

(step: bill_payment).

Bad Request Errors

Gateway Errors

Biller Catalogue Errors

Errors returned by

Fetch Billers

and

Fetch Biller Categories

(step: biller_info_fetch).

Bad Request Errors

Biller Plan Errors

Errors returned by

Fetch Biller Plans

(step: biller_plan_fetch).

Bad Request Errors

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.