> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误码

> Stablecoin Account API 的错误响应结构、状态码，以及各类错误的恢复方式。

[Stablecoin Account API 发布方声明](/zh/stablecoin-account/v1.6/guide/stablecoin-account-api-publisher-disclaimer)

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

```json theme={null}
{
  "code": 422,
  "message": "Insufficient balance"
}
```

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

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

<h2 id="status-codes">
  状态码
</h2>

| `code` | 含义                                                          | 处理方式                                                                                                      |
| ------ | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `400`  | 请求有误 —— 缺少必填参数或某个值未通过校验。                                    | 修正请求。`message` 会指出出错的字段或规则（例如下方列出的 Travel Rule 校验错误）。                                                     |
| `401`  | 未授权 —— 未提供有效 token，或 token 已过期。                             | 通过 [Access Token](/zh/account-center/v1.6/api-reference/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` 联系支持团队。                           |

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

<h2 id="business-rule-errors-to-expect">
  需要预案的业务规则错误
</h2>

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

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

<h2 id="failures-after-acceptance">
  受理之后的失败
</h2>

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

<h2 id="related">
  相关页面
</h2>

* [核心概念](/zh/stablecoin-account/v1.6/guide/core-concepts) —— 响应结构与幂等性
* [Travel Rule 合规](/zh/stablecoin-account/v1.6/guide/travel-rule-compliance)
* [沙盒测试](/zh/stablecoin-account/v1.6/guide/testing-in-sandbox) —— 上线前演练错误路径