错误

本指南介绍在使用 API 时出现问题会发生什么。出错在所难免，而且大多数情况下问题出在调用方，而不是我们。下面来看看你可能遇到的一些状态码和错误类型。

收到 API 响应时，你可以通过检查状态码来判断请求是否成功。如果响应不成功，你可以根据错误信息和错误代码找出问题所在，并进行一些基本的调试（然后再联系支持团队）。

在就错误联系支持团队之前，请注意：99% 的已报告错误实际上都是用户错误。因此，在联系 Fystack 支持团队之前，请仔细检查你的代码。

状态码

以下是 Fystack API 返回的各类状态码。你可以据此判断请求是否成功。

Name
2xx
Type
Description
2xx 状态码表示响应成功。
Name
4xx
Type
Description
4xx 状态码表示客户端错误，也就是说问题出在你这一侧。
Name
5xx
Type
Description
5xx 状态码表示服务器错误，你应该不会遇到这类错误。

错误响应格式

当请求失败时，Fystack API 会返回结构化的错误响应。所有错误响应都包含值为 false 的 success 字段、描述性的 message 以及错误 code。对于校验错误，你还会看到一个 errors 数组，其中包含哪些字段未通过校验的详细信息。

错误响应的常见组成部分如下：

Name
success
Type
Description
错误响应中始终为 false。
Name
message
Type
Description
对出错原因的可读描述。
Name
code
Type
Description
内部错误代码，有助于调试。
Name
errors
Type
Description
对于校验错误，包含哪些字段未通过校验以及原因的详细信息。

Standard error response

{
  "success": false,
  "message": "Resource not found",
  "code": 404
}

Validation error response

{
  "success": false,
  "message": "validation error",
  "code": 400,
  "errors": [
    {
      "field": "email",
      "reason": "required"
    },
    {
      "field": "password",
      "reason": "min=8"
    }
  ]
}

错误代码

Fystack API 使用特定的错误代码来帮助确定发生的具体问题。这些代码比单纯的 HTTP 状态码提供更细粒度的信息。

代码	名称	说明
2407	ValidationErrCode	请求数据未通过校验要求时返回。
2408	GenerationErrCode	表示在生成内容或资源时发生错误。
2409	DatabaseErrCode	数据库操作失败时返回。
2410	ConflictErrCode	表示与资源的当前状态存在冲突。
2411	InfraErrCode	发生与基础设施相关的错误时返回。
2412	RedisErrCode	表示 Redis 缓存操作出现问题。
2413	ForbiddenResourceErrCode	用户无权访问所请求的资源时返回。
2414	ForbiddenActionErrCode	表示用户不被允许执行所请求的操作。
2415	UnauthorizedErrCode	需要身份验证但缺失或无效时返回。
2416	ExecutionErrCode	表示在执行命令或进程时发生错误。
2417	NotFoundErrCode	所请求的资源不存在时返回。
2418	EncodingErrCode	表示在编码数据时发生错误。
2419	DecodingErrCode	解码数据出错时返回。
2420	InternalResourceNotFound	表示找不到所需的内部资源。
2421	BadRequestErrCode	请求格式错误或包含无效参数时返回。
2422	InternalErrCode	表示发生了意外的服务器内部错误。

这些错误代码提供了请求出错原因的具体信息。联系支持团队时，请务必附上错误代码，以帮助我们更快地诊断问题。