BBPS error codes — Setu Docs

Reading time — 6 minutes

#Error codes

Typical errors you might come across, and what to do in the face of adversity.

#Sample error object

// Sample error object
{
    "status"  : number, // HTTP status code, (eg 400, 404 etc)
    "success" : false,
    "error"   : {
        "code"    : "string",  // Setu error code
        "title"   : "string",  // Title of the error
        "detail"  : "string",  // Detail of the error
        "docURL"  : "string",  // optional — if there is any documentation about the error
        "traceID" : "string",  // optional — trace
 
        //  The child error array follows a similar pattern as above
        "errors" : [
            "code"    : "string",
            "title"   : "string",
            "detail"  : "string",
            "docURL"  : "string",
        ]
    }
}

#Generic errors

In some rare cases, if Setu is unable determine the exact cause of a failure, Setu will return one of these generic error codes. Contact Setu here with the traceId in the response if you need more help.

400	bad-request	This is a request-level issue.
401	unauthorised	This is a request-level issue.
403	forbidden	This is a request-level issue.
404	entity-not-found	This could be a platform error.
404	path-not-found	It’s likely that the URL to which the request was made is invalid. Verify the URL, or if that doesn’t help, contact Setu.
500	unable-to-fulfil-request	Something went wrong while trying to process the request. Try again in a little bit, or contact Setu.
500	bad-gateway	Try again in a little bit. If that still fails, contact Setu.
503	service-unavailable	It’s likely that the server to which the request was made is down. Try again after some time, or if that doesn’t help, contact Setu.

#Specific errors

These error codes are tailored to respond to a wide variety of failure cases, and to make error handling a lot easier.

400	invalid-param	Please check your request, one of the parameters used does not seem valid. Check the error response for more details.
400	header-not-found	Some of the headers in your request seems to be missing. Check the error response for more details.
400	malformed-request	The request payload seems invalid, and doesn’t conform to the Setu spec. Please fix and try again.
400	invalid-auth-header	The authorisation header in the request seems invalid. It’s likely that the `authorization` header, or the `bearer`, or the JWT token is missing.
400	invalid-signature-header	The signature header is either seems invalid. Either the digest header is malformed, or the signature algorithm is not supported. Please check the response object for more details.
401	jwt-verification-failed	The JWT token used in the request cannot be verified. Please fix that and try again with a proper token.
401	signature-verification-failed	The signature used in the request cannot be verified. Please fix that and try again with a proper signature.
401	jwt-token-expired	The allotted time for the JWT token used in the request seems to have lapsed. Please retry with a new JWT token.
403	request-not-authorised	This particular request does not seem to have the authorisation to perform the operation. Check the error response, and retry with a right `X-Setu-Product-Insance-Id`.
405	method-not-allowed	The HTTP method used to make the API request is not allowed here. Please check the error response for more details.
425	duplicate-request	Looks like you’ve made the exact same request before, with an identical `issuedAt` value in the JWT token. Retry with a new token, with a fresh value.

#Biller errors

These error codes are specific to the biller.

400	insufficient-customer-identifiers	The provided customer identifiers are not enough to uniquely narrow down a customer in our system. Check the error response for more details.
400	customer-not-found	A customer with the provided credentials does not exist in the biller system.
400	bill-not-found	A bill with the provided `billerBillId` does not exist in the biller system.
400	bill-already-fulfilled	Looks like this particular bill has already been paid.

#Payer errors

These error codes are specific to the payer.

400	payment-instrument-not-allowed	Looks like the payment was made with a payment instrument that isn’t supported by the biller.
400	incorrect-payment-scheme	Looks like the payment scheme to pay this particular bill is incorrect.
400	bill-expired	The time period for the bill payment has expired.
400	incorrect-amount	Looks like the payment was made with the wrong amount.
400	bill-already-fulfilled	Looks like this particular bill has already been paid before.
400	biller-not-available	The requested biller seems to be down right now. Sit tight, Setu will notify you when the biller is back up.
400	biller-not-found	The biller with the given ID does not seem to exist. You can use the getBillers API to verify the correct ID.
400	insufficient-customer-identifiers	The provided customer identifiers are not enough to uniquely narrow down a customer in our system. Check the error response for more details.
400	invalid-customer-identifier	The customer identifiers don’t seem to be valid. Check the error response for more details.
400	customer-not-found	There seems to be no customer with the provided identifiers in the biller’s system. Please verify with the customer.
400	bill-not-found	There seems to be no bill with the provided identifiers in Setu’s system. Please recheck and try again.
500	biller-unable-to-fulfil-request	The partner to which the request has to be forwarded is unable to fulfil the request currently.
502	biller-down	The biller seems unreachable right now. Try again in sometime, or contact Setu with the `traceId` in the response.

#Payment processor errors

These error codes are specific to the payment processor.

400	incorrect-charge	One or more of the charge calculations don’t seem to add up. This could either mean that the MDR doesn’t match the payment instrument and scheme, or a simple math error. Investigate further to determine the cause.
400	incorrect-amount	The requested amount for this bill seems wrong. This could mean that the aggregate refund amount does not match the payment or refund transaction amounts. In some cases, it might be that the processing fee amount doesn’t match the charge component amounts.
400	incorrect-transaction-count	The total number of transactions mentioned seems wrong. There are three possibilities for this mismatch—payment transaction count and its aggregate, the refund transaction count and its aggregate, or the total transaction count and its aggregate. Dig deeper to determine the exact cause.
400	settlement-failed	The bill settlement request has failed.

Was this page helpful?