错误码

本页由平台错误码字典自动生成，请勿手工编辑。所有开放 API 的失败响应均返回下列错误码之一，格式为 { code, message, details, traceId }。

排障时请保留 traceId 并提供给技术支持。标注「可重试」的错误请使用相同幂等键（Idempotency-Key）重试，其余错误重试无效，需按处理建议修正后再发起。

认证鉴权

错误码	HTTP	说明	可重试	处理建议
AUTH_MISSING	401	缺少认证头	否	补齐 x-app-id / x-key-id / x-timestamp / x-nonce / x-signature 后重试。
AUTH_TIMESTAMP_EXPIRED	401	请求时间戳超出容忍窗口	是	校准服务器时钟（NTP），使用当前时间重新签名。
AUTH_REPLAYED	401	nonce 重复，疑似重放	否	每次请求生成新的随机 nonce，不要复用历史请求头。
AUTH_SIGNATURE_INVALID	401	签名验证失败	否	按签名规范重建规范化串核对；确认 secret 与 keyId 匹配、body 未被代理改写。
APP_DISABLED	403	应用已停用	否	联系平台运营确认应用状态。

网关策略

错误码	HTTP	说明	可重试	处理建议
API_NOT_SUBSCRIBED	403	未订阅该 API	否	在控制台为应用订阅对应 API 产品后重试。
QUOTA_EXCEEDED	429	超出配额限制	是	按退避策略稍后重试，或申请提升配额。
IDEMPOTENCY_CONFLICT	409	幂等键冲突：同键不同请求体	否	同一业务请求保持请求体不变；新业务请求使用新的 Idempotency-Key。
PROVIDER_UNAVAILABLE	503	上游通道暂不可用	是	指数退避重试；持续失败时以查询接口确认订单终态。

支付

错误码	HTTP	说明	可重试	处理建议
PAYMENT_AMOUNT_INVALID	400	金额非法（必须为正整数分）	否	金额单位为分，检查是否传入了小数或非正数。
PAYMENT_MERCHANT_NOT_BOUND	400	商户未绑定该支付通道	否	在控制台完成商户与通道的绑定并启用。
PAYMENT_STORE_NOT_BOUND	400	门店不属于当前商户或未启用	否	检查 storeId，并确认门店属于当前商户且处于启用状态。
PAYMENT_TERMINAL_NOT_BOUND	400	终端不属于当前商户门店或未启用	否	检查 terminalId，并确认终端、门店和商户归属一致。
PAYMENT_AUTH_CODE_INVALID	400	付款码无效或已失效	否	请付款人刷新微信付款码后重新扫描；不得重用或记录旧付款码。
WECHAT_PAYER_IDENTITY_REQUIRED	400	微信 JSAPI/小程序支付缺少付款人标识	否	获取当前付款人在直连商户或子商户 AppID 下的 openId，并同时传入正确的 scope。
WECHAT_PAYER_IDENTITY_INVALID	400	微信付款人标识不合法	否	openId 必须为 1–128 位非空字符串且不得携带首尾空格；scope 只能是 DIRECT 或 SUB_MERCHANT。
PAYMENT_SESSION_NOT_FOUND	404	收银台会话不存在	否	检查 sessionId 是否正确、是否已过期被清理。
PAYMENT_SESSION_EXPIRED	410	收银台会话已过期	否	由商户服务端使用新的业务请求和幂等键重新创建会话。
PAYMENT_STATE_INVALID	409	当前状态不允许该操作	否	先查询订单最新状态，按状态机允许的迁移操作。
PAYMENT_METHOD_SELECTION_CONFLICT	400	不能同时指定内部通道和支付产品白名单	否	新接入请仅传 paymentProductCodes，由 SmartPay 完成服务端路由。
PAYMENT_METHOD_UNAVAILABLE	409	当前场景没有可用支付方式	否	检查商户产品开通、渠道绑定、应用环境与 scene 是否匹配。
PAYMENT_PRODUCT_NOT_ENABLED	403	商户未获得该支付产品的生产使用权限	否	在运营工作台完成产品审核、上游生产准入和商户能力启用后重试。
PAYMENT_COMMERCIAL_AUTHORIZATION_REQUIRED	403	当前支付配置尚未获得有效商业上线授权	否	使用托管支付方式选择；完成真实验收及五方复核，并确认生产配置、签字权限与证据有效期。
PAYMENT_METHOD_SELECTION_UNAVAILABLE	409	当前会话不支持付款方式选择	否	仅对包含 paymentMethods 的托管收银台会话提交选择。
PAYMENT_METHOD_ALREADY_SELECTED	409	支付方式已经锁定，不能改选	否	继续使用已创建的支付订单；未知结果必须查原单，不得切换方式重下单。
PAYMENT_METHOD_NOT_FOUND	404	支付方式选项不存在	否	刷新托管收银台状态，并提交当前会话返回的 optionId。
PAYMENT_CHANNEL_ERROR	502	支付通道返回错误	是	查看 details 中的通道错误信息；必要时走人工对账。
PAYMENT_NOTIFICATION_INVALID	400	通道通知验签/解密失败	否	确认通道公钥/解密密钥配置正确；该通知不会入账。
PAYMENT_RETURN_URL_NOT_ALLOWED	400	回跳地址来源未登记或不符合 HTTPS 要求	否	在应用配置中登记准确的 HTTPS 来源（协议、域名和端口）后重试。
PAYMENT_SANDBOX_APPLICATION_REQUIRED	403	生产应用禁止使用沙箱通道	否	改用沙箱应用，或为生产应用绑定已通过生产门禁的真实通道。
STATIC_CHECKOUT_ENTRY_NOT_FOUND	404	静态收款入口不存在	否	请重新扫描商户发布的有效收款码。
STATIC_CHECKOUT_ENTRY_UNAVAILABLE	410	静态收款入口已停用	否	联系商户换取新的收款码。
STATIC_CHECKOUT_AMOUNT_INVALID	400	付款金额不在收款入口限额内	否	按页面提示的单笔最低和最高金额重新输入。

退款

错误码	HTTP	说明	可重试	处理建议
REFUND_NOT_ALLOWED	409	订单不满足退款条件	否	仅支付成功且在 180 天内的订单可退款；检查订单状态。
REFUND_AMOUNT_EXCEEDED	400	退款金额超过可退余额	否	累计退款不能超过订单实付金额，先查询已退金额。
REFUND_RATE_LIMITED	429	退款请求过于频繁	是	同一订单退款间隔至少 1 分钟，稍后重试。
REFUND_NOT_FOUND	404	退款单不存在	否	检查 refundId 是否正确、是否属于当前应用。

银行账户

错误码	HTTP	说明	可重试	处理建议
BANK_CONNECTION_NOT_FOUND	404	银行连接不存在	否	在控制台创建并启用银行连接。
BANK_MEMBER_NOT_FOUND	404	银行会员账户不存在	否	先完成会员开户，确认 memberId 正确。
BANK_INSTRUCTION_INVALID	400	银行指令参数非法	否	检查指令类型与必填字段（金额、账户等）。
BANK_INSTRUCTION_NOT_FOUND	404	银行指令不存在	否	检查 instructionId 是否正确。
BANK_SERIAL_CONFLICT	409	银行请求流水号冲突	否	同一业务重试必须复用原 bankRequestSerial；新业务生成新流水号。
BANK_CHANNEL_ERROR	502	银行通道返回错误	是	指令可能处于 UNKNOWN 态，以查询结果为准，勿盲目重发。

智能分账

错误码	HTTP	说明	可重试	处理建议
ALLOCATION_RULE_INVALID	400	分账规则非法	否	分账比例（bp）合计必须等于 10000，接收方需处于启用状态。
ALLOCATION_RULE_NOT_FOUND	404	分账规则不存在	否	检查 ruleId 是否正确、规则是否已停用。
ALLOCATION_RECIPIENT_NOT_FOUND	404	分账接收方不存在	否	先在控制台登记分账接收方。

结算

错误码	HTTP	说明	可重试	处理建议
SETTLEMENT_PLAN_NOT_FOUND	404	结算计划不存在	否	检查 planId；订单支付成功后才会生成结算计划。
SETTLEMENT_ORDER_NOT_ELIGIBLE	409	订单不满足结算条件	否	仅支付成功且带分账意图的订单可创建结算计划。

系统

错误码	HTTP	说明	可重试	处理建议
INTERNAL_ERROR	500	平台内部错误	是	携带 traceId 联系平台排查；写操作用同一幂等键重试是安全的。