---
title: "错误"
description: "本指南介绍在使用 API 时出现问题会发生什么。"
url: https://docs.fystack.io/zh/errors
last_updated: 2026-11-13
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.fystack.io/llms.txt
> Use it to discover all available pages before exploring further.

# 错误

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

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

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

---

## 状态码

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

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

---

## 错误响应格式

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

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

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

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

```json
{
  "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 | 表示发生了意外的服务器内部错误。 |

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