错误处理

为了简化客户端的错误处理逻辑，我们的 API 采用了统一的响应结构。

错误响应机制

与传统的 REST API 不同，当发生业务逻辑错误时，我们的 API 仍然会返回 HTTP 200 OK 状态码。

请勿仅依赖 HTTP 状态码来判断请求是否成功。您应当检查响应体中的 code 字段。

响应结构

当请求失败时，API 将返回如下 JSON 结构：

{
  "code": 100101,
  "message": "Payment link not found: We can not found payment link of id link_xyz...",
  "data": null
}

• code: 整数类型的错误码。
  • 0 (或缺省): 表示请求成功。
  • 非 0: 表示请求失败。
  • 完整错误码请阅读 错误码表 →
• message: 人类可读的错误描述，部分错误会携带具体的动态信息（如具体的 ID）。
• data: 在错误情况下通常为 null或不提供。

关键提示

在使用 HTTP 客户端（如 Axios, Fetch, RestTemplate）时，请勿将拦截器配置为仅拦截 HTTP 4xx/5xx。您需要在业务层判断 response.body.code 是否为非零值。