Errors & HTTP Codes

All errors return JSON with success: false and a message.

HTTP Status Codes

Code	Meaning
`200`	Success
`400`	Validation error or bad request
`401`	Invalid API credentials
`402`	Insufficient wallet balance
`403`	IP not whitelisted or account inactive
`404`	Payout not found
`409`	Duplicate `reference_id`
`429`	Rate limit exceeded

Message	Resolution
`Insufficient wallet balance`	Load wallet — required amount includes fee + GST
`Beneficiary is not validated`	Validate beneficiary via merchant panel or pass validated `beneficiary_id`
`Beneficiary requires penny drop validation`	Complete penny-drop in Merchant Panel → Beneficiaries
`Merchant agreement must be accepted`	Accept terms in Merchant Panel → Agreement
`Daily / monthly payout limit exceeded`	Reduce amount or contact admin to adjust limits
`Reference ID already exists`	Use unique reference_id per payout
`Invalid API credentials`	Check API Key and Secret Key
`IP address not whitelisted`	Add server IP in API Management
`No active payout gateway assigned`	Contact admin to assign payout channel
`Payout not found`	Verify reference_id belongs to your account