跳到主要内容

错误处理（Error handling）

处理错误和异常的最佳实践。

在某些情况下，API 可能会返回错误。一般来说，错误分为服务端错误和客户端错误两类。

客户端错误​

如果 API 请求格式有误，API 会返回 400~499 范围的 HTTP 状态码。

根据具体的客户端错误类型，响应可能如下：

  • 400 Bad request - 请求通过了认证和授权，但缺少必要数据或数据格式不正确。
  • 401 Unauthorized - Bearer 令牌无效，无法授权 API 调用。可通过 List 4XX errors API 查看详细原因。
  • 403 Forbidden - Bearer 令牌有效，但无权限访问资源。可能是 JWT 权限不足、API key 权限受限或资源被锁定。
  • 404 Not found - 资源不存在。部分情况下资源实际存在，但因权限问题返回 403 会泄露信息，因此返回 404。
  • 405 Method not allowed - 请求方法不被识别。
  • 409 Duplicate record - 存在唯一性冲突的记录。请查阅 API 文档了解唯一约束字段。
{
  "type": "error", 
  "code": "bad_request",
  "status": 400,
  "message": "Request failed validation",
  "details": [
    {
      "type": "type_error.uuid",
      "pointer": "/payment_method/buyer_id",
      "message": "value is not a valid uuid",
      "location": "body"
    }
  ]
}

API 参考文档有更详细的客户端错误格式说明。可通过 List 4XX errors API 查看最新的客户端错误及相关请求。

服务端错误​

如遇服务端错误，API 会返回 500~599 范围的 HTTP 状态码。

此类错误无法由客户端解决。如遇 5XX 错误请联系支持团队。

{
    "type": "error",
    "code": "server_error",
    "status": 500,
    "message": "Request could not be processed",
    "details": []
}

API 参考文档有更详细的服务端错误格式说明。

Powered by Docusaurus