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

# 返回码说明

## 错误响应格式

失败响应统一为 HTTP 4xx/5xx + 错误体，`code` 为错误码数值、`reason` 为错误码枚举（业务错误时 `code` 与 HTTP 状态码一致）：

```json theme={"system"}
{
  "code": 400,
  "reason": "PARAM_ERROR",
  "message": "参数错误,参数[merchant_code]",
  "metadata": {}
}
```

| 字段 | 说明 |
| - | - |
| `code` | 错误码数值（int32），业务错误时与 HTTP 状态码一致；网关层拒绝存在例外，见下文 |
| `reason` | 错误码枚举（ErrorReason），机器可读 |
| `message` | 可读描述，参数类错误带出错字段名 |
| `metadata` | 附加定位信息（如当前状态、出错字段），可为空 |

错误码枚举来自平台**统一错误中心**，与平台其他业务共用同一套 reason，语义一致。

## 网关层错误码（签名与鉴权）

网关在验签、身份识别阶段直接返回，不进入业务处理：

| HTTP | reason | 场景 |
| - | - | - |
| 400 | `NO_AUTH` | `Client-Id` 不存在/已停用（app\_key 无效），或请求体读取失败 |
| 401 | `PARAM_ERROR` | `Timestamp` / `Nonce-Str` 缺失，或时间戳格式非法 |
| 401 | `NO_AUTH` | 时间戳超窗（±5 分钟外）、nonce 重放、签名比对不一致 |
| 500 | `UNKNOWN` | 网关内部错误 |

> [!NOTE]
>
> 网关层拒绝时 HTTP 状态码与错误体 `code` 不一致：验签失败 HTTP 401 而 body `code` 为 `NO_AUTH`（403），app\_key 无效 HTTP 400 而 body 同为 `NO_AUTH`（403）。判断错误原因以 `reason` 为准。错误体**同样携带签名**；app\_key 无效时平台无法取得密钥，该签名无法验证，此时仅依据 HTTP 状态码与错误体判断。

## 业务层错误码（进件/认证域）

| HTTP | reason | 场景 |
| - | - | - |
| 400 | `INVALID_REQUEST` | 无效的请求：业务校验失败（如当前状态不允许的操作） |
| 400 | `PARAM_ERROR` | 参数错误：字段缺失/格式不正确，`message` 带出错字段名 |
| 400 | `NOT_FOUND` | 记录不存在：申请单/认证申请不存在 |
| 400 | `MERCHANT_NOT_EXIST` | 商户号不存在 |
| 400 | `MERCHANT_DUPLICATE` | 商户重复：主体信息已存在 |
| 400 | `PARTNER_NOT_EXIST` | 渠道商不存在 |
| 400 | `ATTACHMENT_NOT_EXIST` | 附件不存在：`key` 无效或已过期 |
| 400 | `INVALID_UPLOAD_FILE_NAME` | 文件名无效 |
| 400 | `INVALID_UPLOAD_FILE_TYPE` | 不支持的文件类型 |
| 400 | `INVALID_STATUS_TRANSITION` | 当前状态不允许此操作：状态机校验失败 |
| 400 | `BUSINESS_ERROR` | 通用业务错误：未细分场景 |
| 401 | `UNAUTHORIZED` | 调用方身份无效（app\_key 未认证或主体身份缺失） |
| 403 | `PERMISSION_DENIED` | 数据权限不足：越权访问（跨渠道商操作他人商户） |
| 403 | `NO_AUTH` | 无权限：通用鉴权拒绝 |
| 403 | `FREQUENCY_LIMITED` | 频率超限：触发限流 |
| 500 | `SYSTEM_ERROR` | 系统错误：服务端异常，请稍后重试或联系平台 |

> [!NOTE]
>
> 商户录入重复提交（同一调用主体、同一 `out_apply_no`）属于幂等例外，不返回错误，返回 HTTP 200 与已受理申请单的当前状态，不重复建商户。

## 使用约定

1. `reason` 用于机器判断，`message` 用于展示给用户，两者配套使用；
2. 渠道商报障时提供 `apply_no`（或 `out_apply_no`/`merchant_code`）与请求时间，平台据此定位链路日志；
3. 渠道侧（易生/易宝等）原始返回码不参与对外错误码语义，仅在进件进度与通知的 `channel_return_code` 字段透传；
4. 错误码的新增与调整随文档版本说明同步发布。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.