错误码

Stablecoin Account API 发布方声明 Stablecoin Account API 调用失败时，响应会返回非 2xx 的 code 和一段可读的 message，结构与成功响应一致：

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

字段	含义
`code`	与 HTTP 状态码一致。可基于它做粗粒度分支处理。
`message`	对错误原因的可读描述。可以记录日志，也可以基于它做更细的分支处理，但不要原样展示给最终用户。

成功的调用始终返回 code: 200 —— 即使 HTTP 状态是 200，也要检查它。

状态码

`code`	含义	处理方式
`400`	请求有误 —— 缺少必填参数或某个值未通过校验。	修正请求。`message` 会指出出错的字段或规则（例如下方列出的 Travel Rule 校验错误）。
`401`	未授权 —— 未提供有效 token，或 token 已过期。	通过 Access Token 获取新的访问令牌，并用新的 `x-auth-token` 请求头重试。
`403`	无权限 —— token 缺少执行该操作或访问该账户的权限。	检查 `x-on-behalf-of` 请求头指向的是否是你可代表的子账户；否则请联系你的 UQPAY 解决方案工程师确认缺失的权限。
`404`	未找到 —— 请求的资源不存在。	检查 `order_id` 或 `address_id`；注意部分查询只接受长 UUID 形式。
`409`	冲突 —— 通常是幂等键冲突：同一个 `x-idempotency-key` 被用于不同的请求，或原始请求仍在处理中。	只在原样重试同一请求时复用同一个 key。如果第一个请求可能仍在处理，请等待并查询资源，不要重复提交。
`422`	无法处理 —— 请求格式正确，但违反了业务规则，例如 `Insufficient balance`。	解决业务问题（补足余额、把金额提高到最小值以上、刷新过期报价）后重新提交。
`500`	内部错误。	用同一个 `x-idempotency-key` 重试，避免重试导致重复创建订单。若持续出现，请携带响应头中的 `x-response-id` 联系支持团队。

每个响应都包含 x-response-id 响应头（UUID）。请记录它 —— UQPAY 支持团队用它定位具体请求。

以下 message 值代表你的集成应当专门处理、而不是当作一般性失败的情形：

Message	触发条件	恢复方式
`Insufficient balance`	卖出/提现金额超过 `available_balance`。	提交前先用 Retrieve Asset 检查；注意在途订单会把资金占用在 `frozen_balance` 中。
`missing travel_rule_data for binance withdraw`	Create Withdraw 的目标经 Binance 通道、且地址簿条目没有 Travel Rule 数据。	通过 Update Address Book 补录 `meta_data` 后重新提交。参见 Travel Rule 合规。
`invalid wallet_type` / `invalid address_party` / `invalid entity_type`	`meta_data` 对象中出现枚举之外的取值。	使用 Travel Rule 字段参考中的准确取值。
`individual third party requires first_name and last_name`	第三方个人受益人缺少姓名字段。	收集缺失的受益人字段后重新提交。
`corporation third party requires company_name`	第三方企业受益人缺少公司名称。	收集缺失的受益人字段后重新提交。
`third party requires country and city`	第三方受益人缺少所在地字段。	从 List Countries 和 List Regions 取值填充。
`hosted wallet requires vasp_id or vasp_name`	托管钱包的 `meta_data` 缺少 VASP 标识。	通过 List VASPs 查询 VASP，或直接提供交易所名称作为 `vasp_name`。

code: 200 只代表订单被受理，不代表它一定会成功。充值、提现、兑换和转账仍可能异步进入 Failed（或 Submit Failed）状态 —— 请关注对应的 webhook（ramp.*.failed 事件），并在订单存在 message 字段时把它作为失败原因。