HTTP状态码与错误处理

更新时间: 2026-08-21 02:20

商户系统先用 HTTP 状态码判断响应大类，再用响应体 error.code 确认具体业务或接入原因。每个具体接口页面底部会列出该接口涉及的错误码。

响应大类

2xx 表示平台已受理并处理本次接口调用。v1 普通开放接口成功响应统一使用 200。创建类接口表示已创建订单或命中已有幂等订单；商户应继续按响应体 status、查单接口或 Webhook 判断最终业务结果。

4xx 表示请求存在商户侧问题。被拒绝的创建类请求不会新建订单，商户需要修正参数、凭据、权限、产品配置或请求频率后再处理。余额不足等明确业务拒绝场景，商户可按自身订单模型将本次尝试置为失败。

5xx、超时、断连或无法验证的响应，可能无法确认订单是否已经创建。商户必须先按原 merchantOrderNo 查询同类型订单；连续查询一段时间仍查不到时，只能使用同一 merchantOrderNo 和完全一致的业务请求，不得换单号或并发创建。

常见 HTTP 状态码

HTTP状态码	描述	商户如何处理	常见错误码
`200`	接口调用成功。创建类请求已受理或命中幂等订单；查询类请求查询成功。	读取响应体。订单类业务结果以 `status`、查单接口或 Webhook 为准。	无
`400`	Path、Query、Header 或 Body 校验失败。	按 `error.code` 和接口字段说明修正请求。	`INVALID_REQUEST`, `INVALID_JSON`, `PARAMETER_INVALID`, `PARAMETER_MISSING`, `AMOUNT_FORMAT_INVALID`
`401`	API Key、时间戳、随机串或签名校验失败。	检查凭据、时钟、签名原文和签名请求头。	`INVALID_API_KEY`, `INVALID_SIGNATURE`, `TIMESTAMP_INVALID`, `NONCE_REPLAYED`
`403`	商户、凭据或产品权限拒绝。	检查准入、产品开通和 API Key 状态；来源 IP 准入由安全组、WAF 或 API Gateway 的运营策略负责，不属于应用错误码合同。	`PERMISSION_DENIED`, `PRODUCT_NOT_ENABLED`
`404`	接口或商户订单不存在。	确认接口地址和原始 `merchantOrderNo`。	`NOT_FOUND`, `ORDER_NOT_FOUND`
`409`	商户订单号与已有业务订单冲突。	停止带着变化后的业务值重试，并先查询既有订单。	`MERCHANT_ORDER_NO_CONFLICT`
`413`	请求体超过 64 KiB。	缩小请求 payload。	`REQUEST_BODY_TOO_LARGE`
`415`	请求体媒体格式不被接受。	POST 请求发送 UTF-8 JSON 请求体。	`UNSUPPORTED_MEDIA_TYPE`
`422`	业务校验拒绝请求。	修正金额、余额、产品、收款人、银行或限额等业务字段。	`BUSINESS_REJECTED`, `INSUFFICIENT_BALANCE`, `AMOUNT_LIMIT_EXCEEDED`, `AMOUNT_PRECISION_INVALID`, `BANK_UNSUPPORTED`, `PRODUCT_UNSUPPORTED`, `COUNTRY_UNSUPPORTED`, `CURRENCY_UNSUPPORTED`, `RECIPIENT_INVALID`
`429`	请求过于频繁。	降低频率，继续创建前先查询已有创建尝试。	`FREQUENCY_LIMITED`
`500`	非创建接口服务内部错误。	短暂等待后重试非创建请求；符合合同的创建响应不使用该状态。	`INTERNAL_ERROR`
`502`	非创建接口的网关或上游依赖异常。	短暂等待后重试非创建请求；如果创建响应无法验证，不要直接重发，先按原 `merchantOrderNo` 查单。	`GATEWAY_ERROR`
`503`	平台无法确认创建结果，或非创建接口/依赖暂时不可用。	如果 `error.code` 是 `ORDER_RESULT_UNKNOWN`，先按原 `merchantOrderNo` 查单；连续查询一段时间仍查不到时，只能用同一单号和原请求重试。	`ORDER_RESULT_UNKNOWN`, `SERVICE_UNAVAILABLE`
`504`	非创建接口的网关或上游依赖超时。	短暂等待后重试非创建请求；如果是创建响应无法验证，先按原 `merchantOrderNo` 查单。	`GATEWAY_TIMEOUT`

错误响应体

所有错误使用统一结构：

json

{
  "error": {
    "code": "PARAMETER_INVALID",
    "message": "amount.value must be a positive decimal string."
  }
}

所有普通 API 响应都会在响应 Header 返回 Request-Id；错误响应体包含稳定的全大写 error.code。错误体字段说明见基本规则。

常见错误码示例

HTTP状态码	错误码	描述	商户如何处理
`400`	`PARAMETER_INVALID`	请求参数不符合接口契约。	按接口字段说明修正请求。
`400`	`AMOUNT_FORMAT_INVALID`	`amount.value` 不是正数十进制字符串。	按主币种单位传字符串，例如 `100.50`；不要传 JSON number、科学计数法或负数。
`422`	`AMOUNT_PRECISION_INVALID`	`amount.value` 小数位超过所选产品和币种允许精度。	按支持国家与币种中的 `amountScale` 调整金额。
`401`	`INVALID_SIGNATURE`	签名请求头未通过校验。	检查 API Key、时间戳、随机串、请求 URL、请求体和 API Secret。
`403`	`PERMISSION_DENIED`	商户、Key 或产品权限不允许。	在商户后台检查准入、Key 状态和产品开通情况。
`404`	`ORDER_NOT_FOUND`	当前商户订单号不存在订单。	确认 `merchantOrderNo` 并查询正确的订单类型。
`409`	`MERCHANT_ORDER_NO_CONFLICT`	商户订单号已存在且业务值不一致。	查询已有订单，停止带着变化后的业务值重试。
`401`	`NONCE_INVALID`	Nonce 缺失或不符合请求 Header 合同。	生成新的受限长度 Nonce，重新计算签名后再请求。
`422`	`COUNTRY_UNSUPPORTED`	当前商户或资源不支持请求的国家。	按已开通产品或余额目录选择支持国家。
`422`	`CURRENCY_UNSUPPORTED`	当前国家、产品或商户不支持请求的币种。	按已开通产品或余额目录选择支持币种。
`422`	`PRODUCT_UNSUPPORTED`	当前国家、币种或商户不支持该产品。	使用商户后台或支持产品编码目录中已开通的产品编码。
`422`	`RECIPIENT_INVALID`	收款人账户信息校验失败。	修正收款人字段后再重试。
`422`	`INSUFFICIENT_BALANCE`	商户账户余额不足，无法完成代付。	充值、降低金额或等待资金到账后再新建代付。
`502`	`GATEWAY_ERROR`	非创建接口的上游网关返回异常错误或非法响应。	短暂等待后重试。
`503`	`ORDER_RESULT_UNKNOWN`	平台无法确认创建请求是否已产生订单，错误响应不含 `platOrderNo`。	先按原 `merchantOrderNo` 查询同类型订单；连续查询一段时间仍查不到时，只能使用同一单号和完全一致的原请求重发。
`503`	`SERVICE_UNAVAILABLE`	非创建 API 或必要依赖暂时不可用。	短暂等待后重试。
`504`	`GATEWAY_TIMEOUT`	非创建接口的上游网关超时。	短暂等待后重试。
`429`	`FREQUENCY_LIMITED`	请求过于频繁。	降低请求频率，短暂等待后再重试。
`500`	`INTERNAL_ERROR`	非创建接口的服务内部错误。	短暂等待后重试。

排障信息

报障只提供环境、UTC 时间、operation、HTTP 状态、Request-Id 响应 Header、响应 Body error.code 和商户订单号；如涉及付款凭证或收款机构核实时，再提供 referenceNo。禁止发送 Secret、签名请求头值、recipient 账号或完整请求 Body。

HTTP状态码与错误处理 ​

响应大类 ​

常见 HTTP 状态码 ​

错误响应体 ​

常见错误码示例 ​