Skip to main content
启润支付使用标准 HTTP 状态码来表示 API 请求的成功或失败。

HTTP 状态码

错误响应格式

由 API 应用层处理的错误使用以下 JSON 结构。认证中间件和代理错误的响应体可能为空或采用其他格式,请先检查 HTTP 状态再解析 JSON。
error 是可选字段,有字段详情时才包含。field 和 reason 也可能分别省略。不要依赖错误信息的固定文本。

应用错误码

这些错误码表示错误条件。业务错误可能使用 HTTP 400,不要根据 code 的前几位推断 HTTP 状态。

常见错误

400 错误请求

请求体或参数无效时返回。

401 未认证

API 密钥缺失或被拒绝时返回。认证入口不保证返回 JSON 响应体。应用层未认证错误若返回 JSON,其 code 为 40101。

404 未找到

请求的资源不存在时返回。

429 请求过多

超过配置的频率限制时返回。默认值为普通 API 请求每个 IP 每分钟 100 次,POST /v1/checkouts 创建收银台为每个已认证商户每分钟 60 次。限制可配置,不代表生产环境保证提供的配额。
在你的集成中实现指数退避策略,以优雅地处理频率限制。

成功响应格式

公开商户 JSON API 的成功响应包含 code: 0 和 message: "success"。Epay 兼容响应和文件下载使用各接口规定的格式。
对于分页接口,data 字段包含 items 和 pagination: