Understanding the response structure

A typical API response will follow the following structure unless explicitly mentioned in the API Reference:

{
    "code": 0,
    "data": {
        ...
    },
    "message": "SUCCESS"
}

Here, a code 0 means that the API returned a success response. We also added an explicit "SUCCESS" message to make it obvious.

Error codes and messages to expect

We have dedicates codes for different errors handled by us to enable our Gateway partners to write custom handling on top of them. All such errors are listed below:

Title	Error Code	Error Message	HTTP Status
InvalidRequest	4000	invalid_request	400
PartnerInactive	4001	partner_inactive	401
GuestNotAllowed	4003	guest_not_allowed	401
InteractionExpired	4004	interaction_expired	401
InvalidIntent	4005	invalid_intent	400
InvalidInteraction	4006	invalid_interaction	400
InvalidIntentConfig	4007	invalid_intent_config	400
ApiSecretMismatch	4008	api_secret_mismatch	401
InvalidAuthToken	4009	invalid_auth_token	401
InvalidLender	4010	invalid_lender	401
LIDValidationFailed	4011	intent_not_allowed	400
InvalidReferrer	4012	invalid_referrer	401
NoActiveStocksLoan	4015	no_active_stocks_loan	400
WithdrawApplicationNotApproved	4201	intent_not_allowed	400
WithdrawApplicationInactive	4202	intent_not_allowed	400
WithdrawClosureUnderProcess	4203	intent_not_allowed	400
WithdrawLoanClosed	4204	intent_not_allowed	400
WithdrawMultipleDisbursementNotAllowed	4205	multiple_disbursement_not_allowed	401
WithdrawNoCashAvailableForWithdrawal	4206	no_cash_available_for_withdrawal	401
WithdrawAmountNotWithinLimit	4207	withdrawal_amount_not_within_limit	401
WithdrawNotAllowedInCaseOfShortfall	4208	withdrawal_not_allowed_in_case_of_shortfall	401
WithInvalidPAN	4209	Invalid PAN shared. Please share individual PAN	401
LenderProductTypeMismatch	4301	lender_product_type_mismatch	400
InvalidLenderProductTypeCombination	4302	invalid_lender_and_product_type_combination	400
InvalidProductType	4303	invalid_product_type	400
TopUpNotAllowed	4308	top_up_not_allowed	400
InvalidAssetType	4309	invalid_asset_type	400
PhoneAlreadyUsed	3002	Phone already used	403
InternalServerError	2000	internal_server_error	500
UserCancelled	1012	user_cancelled	200
ContactSupport	1031	contact_support	200

Smart context in client-side errors

It is infuriating when an API returns "Invalid request payload" without specifying exactly what was wrong with the payload. We are well-versed with this issue and figured out an ingenious solution.

We append the error message with a suffix to provide additional context on what was specifically wrong with the request when throwing a client-side error (i.e. HTTP 4xx).

This will save our Gateway partners from integrating with dozens of error codes even for simple integrations, and, at the same time, allow a more advanced error handling for Gateway partners who want to take things to the next level.

Note that the error codes will remain the same. The suffix will only be added to the error message to provide additional context on the error.

Title	Suffix	Resulting Error Message
InvalidPartner	partner	invalid_request:partner
InvalidIntent	intent	invalid_request:intent
InvalidInteraction	interaction	invalid_request:interaction
InvalidUserId	userId	invalid_request:userId
InvalidLID	lid	invalid_request:lid
InvalidFlowId	flowId	invalid_request:flowId
InvalidIntentConfig	intent_config	invalid_request:intent_config
InvalidSDKType	sdk_type	invalid_request:sdk_type
InvalidSDKVersion	sdk_version	invalid_request:sdk_version
InvalidWebhookEvent	webhookEvent	invalid_request:webhookEvent
InvalidSmallboardToken	smallboardToken	invalid_request:smallboardToken
InvalidLender	lender	invalid_request:lender
PhoneAlreadyUsed	phone_already_used	invalid_request:phone_already_used
AuthContactRequired	auth_contact_required	invalid_request:auth_contact_required
PartnerWebhook	-	partnerWebhook