## 8. 错误码详解（Error Code Reference）

Payment、Crypto Withdrawal 和 Fiat Payout 使用不同的接口与错误响应语义，因此本页按业务形态分别列出错误码。

| 业务形态 | API 范围 | 错误响应特点 |
|  --- | --- | --- |
| [支付（收单）](#81-%E6%94%AF%E4%BB%98%E6%94%B6%E5%8D%95%E9%94%99%E8%AF%AF%E7%A0%81) | `/v1/acquiring/*` | 使用标准的 `code`、`message` 和可选 `detail` 响应 |
| [加密货币提现](#82-%E5%8A%A0%E5%AF%86%E8%B4%A7%E5%B8%81%E6%8F%90%E7%8E%B0%E9%94%99%E8%AF%AF%E7%A0%81) | `/v2/funds/withdraw*` | 核心业务错误可能返回 HTTP 200，同时应用层 `code` 非零 |
| [法币付款](#83-%E6%B3%95%E5%B8%81%E4%BB%98%E6%AC%BE%E9%94%99%E8%AF%AF%E7%A0%81) | `/v2/payouts*` | 返回稳定的 `data.error` 标识与 `data.retryable` 重试提示 |


### 8.1 支付（收单）错误码

以下错误码适用于[收单 API 文档](/zh/docs/en/6-api-ducumentation)中的订单、支付和订阅接口。

> **最小金额：** 加密货币收单订单金额必须大于 `0.1`；法币支付方式（卡支付、Apple Pay 和 Google Pay）的金额最低为 `16`。


#### HTTP 400（请求异常）

| `Code` | 描述 |
|  --- | --- |
| 400 | 请求参数不合法 |
| 40001 | `request_id` 需为有效 UUID |
| 40002 | 过期时间无效：`expires_at` 必须为未来时间 |
| 40003 | `amount` 必须为正数 |
| 40004 | 金额最多支持 6 位小数 |
| 40005 | 缺少 `expires_in` 参数 |
| 40006 | `amount` 必须大于 0.1 |
| 40007 | 链或代币不在支持列表 |
| 40008 | `success_url` 不符合规范 |
| 40009 | `failure_url` 不符合规范 |
| 40010 | 金额无效：未找到匹配的支付方式 |
| 40013 | 支付方式未启用：所请求的支付方式对此商户不可用，或仅开启卡支付但金额过小 |


#### HTTP 401（未授权）

| `Code` | 描述 |
|  --- | --- |
| 401 | 认证失败或签名无效 |


#### HTTP 403（禁止访问）

| `Code` | 描述 |
|  --- | --- |
| 403 | 请求被策略拒绝 |
| 46001 | 创建该 Payment 前必须完成 KYC 验证 |


#### HTTP 404（资源不存在）

| `Code` | 描述 |
|  --- | --- |
| 404 | 对象不存在 |
| 40401 | 订单不存在 |
| 40402 | 支付不存在 |


#### HTTP 409（业务冲突）

| `Code` | 描述 |
|  --- | --- |
| 40901 | `request_id` 重复 |
| 40902 | `client_reference` 重复 |
| 40903 | 存在有效支付，请使用已有 Payment 或等待其过期 |
| 40904 | 支付处理中，暂不可创建新 Payment |
| 40905 | Token 无权操作该订单 |
| 40906 | 订单已过期 |
| 40907 | 订单已完成或过期，无法创建 Payment |
| 40908 | 由于存在待处理的 Payment，无法创建新 Payment |
| 40909 | 该订单已存在进行中的入金订单 |
| 40910 | 金额低于卡支付允许的最小值 |
| 40911 | 金额超过卡支付允许的最大值 |
| 40912 | 您所在的地区不支持购买 |


#### HTTP 500（服务器内部错误）

| `Code` | 描述 |
|  --- | --- |
| 500 | 内部异常，请联系支持团队 |


### 8.2 加密货币提现错误码

以下错误码适用于[资金 API 文档](/zh/docs/en/fund-api#withdraw-organization-funds)中的组织加密货币提现接口。

| `Code` | HTTP 状态码 | 说明 |
|  --- | --- | --- |
| `401` | 401 | 应用层无法认证 API Key |
| `403` | 403 | API Key 缺少 `fund.withdraw` 权限、IP 白名单校验未通过，或所选链/代币组合未启用提现 |
| `30001` | 200 | 核心提现配置拒绝了所选代币 |
| `30002` | 200 | 组织的扣款资金账户不存在 |
| `30003` | 200 | 扣款账户的可用余额不足 |
| `30005` | 200 | 提现金额超过当日剩余限额 |
| `30007` | 200 | 提现金额低于最低要求，或金额不大于相关手续费 |
| `30012` | 200 | 所选链/代币组合没有可用的提现手续费配置 |
| `30013` | 400 或 200 | 请求参数无效，例如 UUID、链/代币组合、金额、精度、扣款币种或钱包地址无效 |
| `30022` | 200 | 目标地址是 Infini 内部地址；请改用内部转账 |
| `30023` | 200 | 扣除锁定或预留资金后，可用余额不足 |
| `30034` | 200 | `source_currency` 为 `USD`，但组织未开通 USD Cash Account |
| `80016` | 200 | 暂时无法获取所需的资产价格或汇率 |
| `500` | 500 | 发生未预期的内部错误或下游服务错误 |


核心资金服务错误使用标准应用层响应；即使 `code` 非零，HTTP 状态也可能是 200。由网关直接拒绝的 HMAC 校验错误可能不包含应用层错误码。

### 8.3 法币付款错误码

以下错误码适用于[法币付款 API 文档](/zh/docs/en/payout-api#error-codes)中的银行账户付款接口。本汇总页使用 `code` 进行程序判断；`data.error`、适用接口和可重试信息请查看 Payout API 中的详细错误码表。

| `Code` | HTTP 状态码 | 说明 |
|  --- | --- | --- |
| `30013` | 400 | 请求字段缺失、格式错误、不支持或彼此不一致。修正字段后重新提交。 |
| `401` | 401 | HMAC 或应用鉴权失败。检查 API Key、签名、Date、Digest 和参与签名的请求路径。 |
| `403` | 403 | API Key 缺少所需权限、IP 策略拒绝请求，或组织无权访问对应资源。 |
| `40302` | 403 | 组织没有 USD 付款账户。 |
| `404` | 404 | 当前鉴权组织下不存在该 `quote_id` 或 `payout_id`。 |
| `409` | 409 | `client_reference_id` 已被不同业务数据使用。不同的逻辑付款必须使用新的引用。 |
| `40901` | 409 | Quote 已被消费，请重新获取 Quote。 |
| `40902` | 409 | Quote 已不再处于可用状态，请重新获取 Quote。 |
| `40903` | 409 | 当前组织已有另一笔付款正在提交。短暂随机退避后重试。 |
| `40904` | 409 | USD 付款账户配置不一致，请联系 Infini 支持。 |
| `42201` | 422 | `amount_mode` 与 `fee_paid_by` 组合不受支持。 |
| `42202` | 422 | Quote 已过期。请重新获取 Quote，不要继续重试过期的 `quote_id`。 |
| `42204` | 422 | Quote 计算或其绑定的收款资料快照暂时不可用，短暂等待后重新获取 Quote。 |
| `42205` | 422 | 金额超过当前支持的付款金额，请降低金额。 |
| `42206` | 422 | `sending_amount` 必须大于 `100 USD`，请提高金额。 |
| `42207` | 422 | 组织 USD 可用余额不足以支付 `sending_amount`，入金后再创建付款。 |
| `42208` | 422 | 该付款会超过账户共享的每日提现限额，请等待下一个限额周期或降低金额。 |
| `100014` | 503 | 付款执行服务或服务商流动性暂时不可用。同一笔逻辑付款稍后重试时继续使用原来的 `client_reference_id`。 |
| `500` | 500 | 发生未预期的内部错误。可安全重试；如果持续出现，请携带 Request ID 联系 Infini 支持。 |