返回码说明 - 星富通科技有限公司

错误响应格式

失败响应统一为 HTTP 4xx/5xx + 错误体，code 为 HTTP 状态码、reason 为错误码枚举：

{
  "code": 400,
  "reason": "PARAM_ERROR",
  "message": "参数错误,参数[merchant_code]",
  "metadata": {}
}

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

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

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

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

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`	系统错误：服务端异常，请稍后重试或联系平台

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