Utility API Response Handling

Enkash’s Uitlity API provides response codes to indicate the outcome of API requests, ensuring clear communication and efficient error handling for businesses. Properly handling these codes is essential for seamless integration and operation.

Below response_code and http status code and handling is applicable for below APIs

Create Bill Without Bill Fetch

Create Bill API

Get Utility Bill by Reference Id

Get Utility Bill Status

Bill Payment Webhook

Response Codes

Code	Description
0	API call Success. Check Payload for more details
1	API call Failure. Check response_code and payload field
36	Velocity limit breach.
37	Velocity limit breach.
38	Duplicate reference Id

Http Response Codes

Code	Description
400	API Request field validation error.
400	no Biller found. Invalid biller id.
412	Mandatory Input parameter missing.
412	Please enter valid value for input. parameter
412	Input paramter type not matching.
422	Biller is not active.
412	Invalid nodal bank in request.
412	Invalid checksum in the request.
412	Invalid Company ID.
412	Bank account and VPA are both provided in the request. Please provide only one to add the beneficiary.
500	Bill fetch failed during validation.
500	Internal Server Error. Check enquiry after 5 mins
502	Server Down
503	Server down
504	Gateway timeout. Check enquiry after 5 mins.

HTTP Status Codes 🚦

2XX (e.g., 200 OK): Success! ✅

This means your API request was successfully processed.

Now, you need to check the billPayStatus and paymentStatus fields in the response payload for the specific outcome of your transaction.

4XX (e.g., 400 Bad Request, 401 Unauthorized): Request Failed ❌

There was a problem with your request. This could be due to invalid data or failed internal checks.

Consider this a request failure. Review your request details and try again. For details check response_code and payload field in response.

5XX (e.g., 500 Internal Server Error, 503 Service Unavailable): Server Issue ⚠️

The server encountered an error or timed out.

Wait 2-3 minutes and then run an enquiry for the transaction.

If the enquiry shows the record with details (see success cases below), the transaction might have eventually processed.

If the enquiry results in 400 httpsStatus with payload "No utility payment found" it means the transaction didn't go through. You can safely retry the original request.

Checking the Payload for 2XX Responses 🧾

If you receive a 2XX status, dive into the JSON payload and check these fields:

billPayStatus: This tells you the status of the bill payment itself.

SUCCESS: 🎉 Bill payment was successful!

FAILED: 😞 Bill payment failed.

Check paymentStatus:

If paymentStatus is FAILED, your wallet debit failed due to insufficient funds.

If paymentStatus is REFUNDED, the bill payment failed, and the funds have been credited back to your wallet.

IN_PROGRESS: ⏳ Bill payment confirmation is pending at the biller's end.

PENDING: ➡️ Your bill payment request has been initiated.

failureReason:

If billPayStatus is FAILED, this field will provide more details about why the payment failed. Check it to understand the cause.

Integration Note

Ensure your application handles all response codes effectively.

Utility API Response Handling