返回码说明 - 星惠付开放平台

错误响应格式

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

{
  "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`	网关内部错误

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

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

使用约定

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