Error Codes

Code	Meaning
200	Request successful.
400	Invalid request format, validation error, insufficient balance, limit exceeded, or permanent bank rejection.
401	Authentication failed. This includes missing or unknown API key, source IP not allowed, expired timestamp, signature mismatch, v1 request with query string, or replayed v2 nonce.
403	Authenticated request is blocked because API access is disabled for the business, usually pending KYC or operational review.
404	Resource not found (typically a beneficiary or payout that doesn't exist or doesn't belong to this business).
409	Conflict, usually an existing beneficiary with the same bank details or VPA.
500	Internal server error.
502	Bridg could not authenticate/configure the partner-bank path. Merchant usually cannot fix this directly.
503	Partner bank temporarily unavailable, payouts paused, or a rail temporarily disabled.

Common error reasons

Reason	HTTP status	What to check
bad_request	400	Payload shape, validation details, inactive beneficiary, unsupported rail, limit violation, or permanent bank rejection.
insufficient_balance	400	Wallet balance must cover payout amount + commission + GST.
rail_beneficiary_mismatch	400	Bank rails need account number + IFSC. UPI rail needs vpa.
unauthenticated	401	Authentication failed. Check API key, signing key, source IP whitelist, timestamp, signature canonical string, query-string signing version, and v2 nonce reuse. The public response is intentionally opaque and does not reveal which authentication check failed.
kyc_required	403	Business API access is disabled. Complete KYC review or contact ops.
not_found	404	Resource is missing, archived/inactive, or belongs to another business.
conflict	409	Duplicate beneficiary payment details.
payouts_paused	503	Ops has paused payout creation. Retry later.
rail_disabled	503	The selected rail is temporarily disabled. Try another rail or retry later.
bank_unreachable	502 or 503	Partner bank path is down, rate-limited, or temporarily uncertain. Retry with the same Idempotency-Key only for the same payout attempt.

Error response shape

Authentication and validation failures return an error object:

{
  "error": "unauthenticated",
  "message": "unauthenticated",
  "requestId": "0296e8ab-3a42-4e82-8d2f-69c6842579d7"
}

Validation failures may include details, hint, field, or code.

Some legacy v1 business responses still use the original envelope shape. For example, duplicate beneficiary creation returns HTTP 409 with the existing beneficiary in data:

{
  "status": 409,
  "data": {
    "beneficiaryId": "50a97363-71bb-47b1-af7f-a55444684a58"
  },
  "message": "Beneficiary already exists",
  "meta": null
}