Onramp Errors

Every error uses the shared merchant API envelope:

{ "code": "VALIDATION_FAILED", "message": "…", "requestId": "…" }

code is the contract. Never parse message; it may be reworded. Quote requestId when reporting an unexpected failure to BLOX.

Shared authentication and HTTP semantics: Errors.

Codes

Status	`code`	Meaning / action
`400`	`INVALID_REQUEST`	`Idempotency-Key` is missing or malformed, `tokenId` is unavailable, the bank list cannot be loaded, or an FPX checkout amount cannot cover its fee. Fix the request or retry the bank list.
`400`	`VALIDATION_FAILED`	A body or query field is malformed or outside its constraint — including a missing `type`, or a `feeMode` sent on a `BLOX_ACCOUNT` checkout. Fix the request.
`400`	`INSUFFICIENT_BALANCE`	`CHARGE_TO_PREFUND` was requested and your checkout prefund cannot cover the fee. No link was created. Top up under Checkout → Top up prefund, or send `DEDUCT_FROM_AMOUNT` instead. Retrying without doing one of those will fail identically.
`401`	`UNAUTHORIZED`	API key or signature headers are missing or invalid. Re-sign the current body with a fresh `created` value.
`403`	`FEATURE_DISABLED`	The checkout type you asked for is not enabled for the account — each is granted separately, so holding one never implies another. The message names the missing one. Contact BLOX.
`403`	`ACCOUNT_FROZEN` / `ACCOUNT_SUSPENDED` / `ACCOUNT_PENDING_VERIFICATION`	The account state blocks money in. Contact BLOX.
`403`	`ACCOUNT_TERMINATED`	The account is terminated; read and write routes are blocked.
`404`	`NOT_FOUND`	The checkout does not exist or belongs to another account.
`422`	`VALIDATION_FAILED`	The idempotency key was already used with a different body on the same route.
`429`	`RATE_LIMITED`	A checkout-create route or account limit was exceeded. Back off before retrying.
`5xx`	`INTERNAL_ERROR`	Unexpected BLOX failure. Reconcile first and report `requestId` if it persists.

Retry guidance

Checkout creation needs one extra safeguard: a retry can create a second unpaid link. No money moves until a customer pays, but two active links can still cause duplicate payment.

Response	What to do
`202`	Wait briefly, sign a fresh request, and retry with the same `Idempotency-Key`
`400`, `422`	Fix the request and use a new key; rejected outcomes are remembered for 24 hours
`401`, `403`	Fix access or signing before retrying
`429`	Back off and retry with the same key; the request did not run
`5xx` or timeout	List checkouts and match your unique `title`; retry with the same key only when the original did not land

Persist the UUID v4 before sending and put your order identifier in title. Full idempotency behavior: Idempotency.