/

to search

Introducing Setu Changelog Check it out ↗

#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.

400bad-requestThis is a request-level issue.
401unauthorisedThis is a request-level issue.
403forbiddenThis is a request-level issue.
404entity-not-foundThis could be a platform error.
404path-not-foundIt’s likely that the URL to which the request was made is invalid. Verify the URL, or if that doesn’t help, contact Setu.
500unable-to-fulfil-requestSomething went wrong while trying to process the request. Try again in a little bit, or contact Setu.
500bad-gatewayTry again in a little bit. If that still fails, contact Setu.
503service-unavailableIt’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.

400invalid-paramPlease check your request, one of the parameters used does not seem valid. Check the error response for more details.
400header-not-foundSome of the headers in your request seems to be missing. Check the error response for more details.
400malformed-requestThe request payload seems invalid, and doesn’t conform to the Setu spec. Please fix and try again.
400invalid-auth-headerThe 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-headerThe 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.
401jwt-verification-failedThe JWT token used in the request cannot be verified. Please fix that and try again with a proper token.
401signature-verification-failedThe signature used in the request cannot be verified. Please fix that and try again with a proper signature.
401jwt-token-expiredThe allotted time for the JWT token used in the request seems to have lapsed. Please retry with a new JWT token.
403request-not-authorisedThis 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.
405method-not-allowedThe HTTP method used to make the API request is not allowed here. Please check the error response for more details.
425duplicate-requestLooks 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.

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

#Payer errors

These error codes are specific to the payer.

400payment-instrument-not-allowedLooks like the payment was made with a payment instrument that isn’t supported by the biller.
400incorrect-payment-schemeLooks like the payment scheme to pay this particular bill is incorrect.
400bill-expiredThe time period for the bill payment has expired.
400incorrect-amountLooks like the payment was made with the wrong amount.
400bill-already-fulfilledLooks like this particular bill has already been paid before.
400biller-not-availableThe requested biller seems to be down right now. Sit tight, Setu will notify you when the biller is back up.
400biller-not-foundThe biller with the given ID does not seem to exist. You can use the getBillers API to verify the correct ID.
400insufficient-customer-identifiersThe provided customer identifiers are not enough to uniquely narrow down a customer in our system. Check the error response for more details.
400invalid-customer-identifierThe customer identifiers don’t seem to be valid. Check the error response for more details.
400customer-not-foundThere seems to be no customer with the provided identifiers in the biller’s system. Please verify with the customer.
400bill-not-foundThere seems to be no bill with the provided identifiers in Setu’s system. Please recheck and try again.
500biller-unable-to-fulfil-requestThe partner to which the request has to be forwarded is unable to fulfil the request currently.
502biller-downThe 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.

400incorrect-chargeOne 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.
400incorrect-amountThe 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.
400incorrect-transaction-countThe 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.
400settlement-failedThe bill settlement request has failed.

Was this page helpful?