Payout Errors
All errors from the merchant API have the same body:
{ "code": "INSUFFICIENT_BALANCE", "message": "…", "requestId": "…" }Use code to identify the error. message is text for persons, and BLOX can change it at any time. Do not parse message. BLOX uses requestId to find the request. Give the requestId to BLOX when you report a 5xx response.
A new code is not a breaking change. A change to a code, or the removal of a code, is a breaking change.
For authentication errors and the shared HTTP envelope, refer to Errors.
Codes
| Status | code | Meaning / action |
|---|---|---|
| 400 | VALIDATION_FAILED | The body does not agree with the schema. For example, the body contains both beneficiaryId and beneficiary, or neither of them. message gives the incorrect fields. |
| 400 | INVALID_REQUEST | The Idempotency-Key is missing or not valid. Or, the bank rejected the beneficiary account as not valid, dormant, closed, or blocked. This check occurs at registration, on an inline beneficiary, and on the verify route. Or, the amount minus the fee is less than the RM1 minimum. |
| 400 | INSUFFICIENT_BALANCE | Add funds to your prefund balance with a dashboard top-up or a bank transfer. Then send the request again. |
| 400 | UNKNOWN_BENEFICIARY | The beneficiaryId does not agree with an active beneficiary on your account. Or, the inline bankCode is not in your /v1/payouts/active-banks list. |
| 400 | BENEFICIARY_NAME_MISMATCH | BLOX returns this code only if you sent nameCheck. The beneficiary name does not agree with the bank record at the level that you requested. BLOX never returns the name from the bank. If you requested strict and the name passes loose, message tells you. Correct the name, then send the request again with a new Idempotency-Key. |
| 400 | NAME_CHECK_UNAVAILABLE | You sent nameCheck, but the bank cannot check the name for this account. The bank is not in the range of the check, or the bank returned no holder name. To register the beneficiary without verification, send the request again without nameCheck. |
| 400 | LIMIT_EXCEEDED | The payout is more than a daily or monthly payout limit of your account. |
| 403 | LIMIT_EXCEEDED | Your account has the maximum number of active beneficiaries. The default maximum is 10,000. Only a new destination increases the number. An inline beneficiary with a destination that you used before does not increase it. Delete the beneficiaries that you do not pay, or ask BLOX to increase the maximum. |
| 401 | UNAUTHORIZED | The API key is missing or not known, the signature headers are missing, or the signature is not valid. A signature with a created time more than 300 seconds before or after the BLOX time is also not valid. Sign the request again with a new created value and the digest of the current body. |
| 403 | FEATURE_DISABLED | Payouts are not enabled on your account. Ask BLOX for help. |
| 403 | ACCOUNT_FROZEN / ACCOUNT_SUSPENDED / ACCOUNT_PENDING_VERIFICATION | The status of your account stops all payments out of the account. Read requests continue to operate. Ask BLOX for help. |
| 403 | ACCOUNT_TERMINATED | BLOX blocks all routes, including read requests. |
| 404 | NOT_FOUND | The payoutId is not known, or the payout is on a different account. |
| 422 | CONFLICT | You used the Idempotency-Key before with a different body. |
| 429 | RATE_LIMITED | You sent more than 300 create requests in one minute. Wait, then send the request again. |
| 503 | SERVICE_UNAVAILABLE | BLOX stopped payout creation for a period. BLOX did not create a payout and did not debit your prefund balance. Send the request again later with the same Idempotency-Key. BLOX also returns this code when it cannot connect to the bank for a beneficiary check, with or without nameCheck. |
| 5xx | INTERNAL_ERROR | An unexpected error occurred at BLOX. message does not give details. Give the requestId to BLOX. |
Retry guidance
| Response | Retry with | Why |
|---|---|---|
401 | Do not retry | Correct your signature or API key first. |
4xx | A new Idempotency-Key | For 24 hours, BLOX returns the same rejection for the same key. |
429 | The same key | BLOX did not process the request. |
500, 503, timeout | The same key | The same key prevents one create request from making two payouts. |
API failures on the dashboard
The dashboard shows each 4xx response to a payout API request that changes data. You can see these responses on the payout API failures page for 30 days. Each entry shows the requestId, method, path, status, code, message, and the Idempotency-Key that you sent. The page marks a response that repeats an earlier result for the same Idempotency-Key.
You can search by requestId or Idempotency-Key, and filter by status or code. The page does not show the request body. The page does not show 401, 429, and 5xx responses. For these responses, give the requestId to BLOX.