Error codes

Stablecoin Account API Publisher Disclaimer When a Stablecoin Account API call fails, the response carries a non-2xx code and a human-readable message in the same envelope as success responses:

{
  "code": 422,
  "message": "Insufficient balance"
}

Field	Meaning
`code`	Mirrors the HTTP status. Branch on it for coarse handling.
`message`	Human-readable description of what went wrong. Safe to log; branch on it for finer-grained handling, but do not surface it verbatim to end users.

Successful calls always return code: 200 — check it even on HTTP 200 responses.

Status codes

`code`	Meaning	What to do
`400`	Bad request — a required parameter is missing or a value failed validation.	Fix the request. The `message` names the offending field or rule (for example the Travel Rule validation errors listed below).
`401`	Unauthorized — no valid token provided, or the token expired.	Request a new access token via Access Token and retry with a fresh `x-auth-token` header.
`403`	Forbidden — the token lacks permission for this operation or account.	Check the `x-on-behalf-of` header targets a sub-account you can act for; otherwise contact your UQPAY solutions engineer about the missing permission.
`404`	Not found — the requested resource does not exist.	Check the `order_id` or `address_id`; note that some lookups accept only the long UUID form.
`409`	Conflict — usually an idempotency collision: the same `x-idempotency-key` was used with a different request, or the original request is still processing.	Reuse the key only for exact retries of the same request. If the first request may still be in flight, wait and query the resource instead of resubmitting.
`422`	Unprocessable — the request is well-formed but violates a business rule, for example `Insufficient balance`.	Resolve the business condition (top up the balance, raise the amount above the minimum, refresh an expired quote) and resubmit.
`500`	Internal error.	Retry with the same `x-idempotency-key` so a retry cannot double-create the order. If it persists, contact support with the `x-response-id` response header.

Every response includes an x-response-id header (UUID). Log it — UQPAY support uses it to trace the exact request.

Business rule errors to expect

These message values indicate conditions your integration should handle deliberately rather than treat as generic failures:

Message	Trigger	Recovery
`Insufficient balance`	The selling/withdrawal amount exceeds `available_balance`.	Check Retrieve Asset before submitting; remember in-flight orders hold funds in `frozen_balance`.
`missing travel_rule_data for binance withdraw`	Create Withdraw to a Binance-routed destination whose address book entry has no Travel Rule data.	Backfill `meta_data` via Update Address Book, then resubmit. See Travel Rule compliance.
`invalid wallet_type` / `invalid address_party` / `invalid entity_type`	A `meta_data` object with a value outside the allowed enums.	Use the exact values from the Travel Rule field reference.
`individual third party requires first_name and last_name`	Third-party individual beneficiary missing name fields.	Collect and resubmit the missing beneficiary fields.
`corporation third party requires company_name`	Third-party corporate beneficiary missing the company name.	Collect and resubmit the missing beneficiary fields.
`third party requires country and city`	Third-party beneficiary missing location fields.	Populate from List Countries and List Regions.
`hosted wallet requires vasp_id or vasp_name`	Hosted wallet `meta_data` without VASP identification.	Look up the VASP via List VASPs, or supply the exchange name as `vasp_name`.

Failures after acceptance

A code: 200 response means the order was accepted, not that it will succeed. Deposits, withdrawals, conversions, and transfers can still end in Failed (or Submit Failed) asynchronously — watch the corresponding webhook (ramp.*.failed events) and treat the order’s message field as the failure reason where present.

Core concepts — the response envelope and idempotency
Travel Rule compliance
Testing in sandbox — exercising error paths before go-live

Getting Started

Assets & Balances

Deposits

Withdrawals

Conversions & Transfers

Reference

Status codes

Business rule errors to expect

Failures after acceptance

​Status codes

​Business rule errors to expect

​Failures after acceptance

​Related

Status codes

Business rule errors to expect

Failures after acceptance

Related