> ## 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` 为 HTTP 状态码、`reason` 为错误码枚举：

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

| 字段         | 说明                      |
| ---------- | ----------------------- |
| `code`     | HTTP 状态码（int），与响应状态一致   |
| `reason`   | 错误码枚举（ErrorReason），机器可读 |
| `message`  | 可读描述，参数类错误带出错字段名        |
| `metadata` | 附加定位信息（如当前状态、出错字段），可为空  |

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

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

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

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

<Note>
  验签失败时 HTTP 状态统一返回 401，与 `reason` 的常规映射（`NO_AUTH`=403）不同；错误体**同样携带签名**，验签失败的响应按请求头参数签名，供渠道商自查。
</Note>

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

| 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`            | 通用业务错误：未细分场景                     |
| 403  | `NO_AUTH`                   | 无权限：越权访问（跨渠道商操作他人商户）             |
| 403  | `FREQUENCY_LIMITED`         | 频率超限：触发限流                        |
| 500  | `SYSTEM_ERROR`              | 系统错误：服务端异常，请稍后重试或联系平台            |

<Note>
  进件重复提交（同 `out_apply_no`）属于幂等例外，不返回错误，返回 HTTP 200 与当前申请单状态。
</Note>

## 使用约定

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