Response & Http Status & Error Codes

Response envelope

{"code": 200, "msg": "SUCCESS", "data": { ... }}

code carries the business outcome. 200 means success; any other value means the request was rejected by business logic. See the error code tables below.
msg is a human-readable description for troubleshooting only. Do not branch on it.
data holds the business payload. It may be empty when code is not 200.

HTTP status codes

Status	Meaning	What to do
`200`	The request reached business logic and ran to completion	Read `code` in the body to determine success or failure
`4xx`	The request was rejected before reaching business logic. The transaction did not happen	Definite failure. Fix the request; you may resend with a new idempotency key
`5xx`	Result unknown. See the next section	Must not be treated as a failure
No response at all (your client times out, connection reset)	Result unknown	Same as `5xx`

Our guarantee: we never use a 4xx to report a request whose outcome is uncertain. If we cannot determine whether your request was executed, you will always receive a 5xx — never a 4xx. This means you can rely on the status class alone and do not need to enumerate individual status codes.
So the decision logic is three lines:

200 → read code in the body.
4xx → definite failure, nothing happened.
Anything else, including no response at all → result unknown.

Result unknown

5xx means we cannot determine the outcome of your request. It may already have been executed successfully upstream — for example, the payout may already have been sent.

Do not treat it as a failure.
Do not parse the response body. In this case the body may not be JSON (it can come from the load balancer). Base your decision on the HTTP status code alone.
If you resend, you must reuse the same merchantReferenceId. Upstream deduplicates on this key, so resending with the same key can never cause a double payout. Resending with a new key can.
To learn the final state, query the transaction by merchantReferenceId.

Error codes

General (1000 range):

code	Meaning
`1001`	Invalid request parameter
`1002`	Resource does not exist
`1003`	Resource already exists
`1004`	Access denied
`1005`	Order is in a final state and can no longer be modified
`1012`	Signature validation failed
`1013`	Order not found
`3003`	This idempotency key has already been accepted. Query the transaction for that key instead;
Balance and payout (`4000` range):
code	Meaning
---	---
`4000`	Insufficient balance
`4001`	Invalid amount
`4002`	Feature not supported
`4004`	Beneficiary details are invalid or incomplete
Other:
code	Meaning
---	---
`601`	System under maintenance. The request was not executed; retry later
`9999`	System error