HTTP Error Codes

BillDesk uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., an api key doesn't have permissions to perform the request, the request conflicts with another request or a mandatory parameter is not present in the request.). Codes in the 5xx range indicate an error with internal or external APIs.

The status code can be '200', if there are validation failures at issuing bank's end, for example : card not enabled for online payment. Though the status code will be '200', the corresponding error object will be returned (same is explained elaborately in 'BillDesk error codes' section).

HTTP Status codes summary

Status code	Description
200 - OK	Request processed successfully
400 - Bad Request	The request was unacceptable, indicating an error that failed given the information provided
401 - Unauthorized	Request authentication is not valid
403 - Forbidden	The credentials doesn't have permissions to perform the request.
404 - Not Found	The requested resource doesn't exist.
409 - Conflict	The request conflicts with another request (perhaps due to using the same idempotent key).
500 - Server Errors	Internal Server Error

BillDesk Error Codes

When you access BillDesk APIs, the responses can be successful or they can respond with failure message. In case of failure, a JSON error response is returned with the relevant error parameters.

The error (code/message) in response helps to:

Analyse top failure reasons and map them internally with your workflows.
Helps to identify the source of failure. It can be due to customer action or external factors (BillDesk, Issuer Bank or Network Scheme).
Helps to identify the payment step and the exact failure reason.

Error Object Structure

The error object in the response contains status, error_type, error_code and message that help identify and solve the error. Check out the sample error response

{
    "status": 422,
    "error_type": "api_validation_error",
    "error_code": "AUAVE0011",
    "message": "Invalid mercid"
}

In the above example, the message states that the merchant id passed by you is not valid. You need to check the correct merchant id and try again.

In certain cases, the error is responded as part of the actual response. Check out below the sample error response in such a scenario.

[
	{
		"objectid": "transaction",
		"transactionid": "X4561137781819",
		"orderid": "orderid12345",
		"mercid": "BDMERCID",
		"transaction_date": "2023-05-06T11:50:33+05:30",
		"amount": "178.00",
		"surcharge": "0.00",
		"discount": "0.00",
		"charge_amount": "178.00",
		"currency": "356",
		"ru": "https://www.merchant.com/ru",
		"txn_process_type": "nb",
		"bankid": "456",
		"itemcode": "DIRECT",
		"bank_ref_no": "123456878",
		"auth_status": "0399",
		"transaction_error_code": "TRPRE0001",
		"transaction_error_desc": "Invalid bank response",
		"transaction_error_type": "payment_response_error",
		"payment_method_type": "netbanking"
	}
]

Error Code Categorization

The error codes are categorized for different workflows at BillDesk. The categories are listed as follows

Error Category	Attributes	Sample Errors
Validation Errors	`error_code`, `error_type`, `message`, `status`	{ "status": 422, "error_type": "api_validation_error", "error_code": "AUAVE0011", "message": "Invalid mercid" }
Transaction Errors	`transaction_error_code`, `transaction_error_type`, `transaction_error_desc`	{ "transaction_error_code": "AUP0000", "transaction_error_type": "pending", "transaction_error_desc": "Authentication Pending" }
Mandate Verification Errors	`verification_error_code`, `verification_error_type`, `verification_error_desc`	{ "verification_error_code": "AUP0000", "verification_error_type": "pending", "verification_error_desc": "Authentication Pending" }
Token Provisioning Errors	`error_code`, `error_type`, `transaction_error_desc`	{ "error_code": "AUP0000", "error_type": "pending", "transaction_error_desc": "Authentication Pending" }
PAR Processing Errors	`par_error_code`, `par_error_type`, `par_error_desc`	{ "par_error_code": "AUP0000", "par_error_type": "pending", "par_error_desc": "Authentication Pending" }

List of Error Reasons for Payments

To download the list of possible error reasons along with their explanation, please download Error Codes List V4.1.