> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poixe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误类型概览

Poixe AI 系统是一层 API 转发与调度层，因此错误大致分为三类。

理解这些分类有助于你更快定位问题、决定是否重试，以及在需要时向团队提供有效信息。

## 1. 上游错误（Upstream）

上游错误来自模型厂商或其网关。常见触发原因包括：

* 请求体不符合协议（字段缺失、类型不匹配、参数非法等）
* 鉴权失败（Key 无效、权限不足）
* 上游限流、过载、服务异常

一般情况下，系统会尽量捕获常见上游错误，并根据错误类型判断是否需要自动重试（例如短暂的过载/限流可能会触发重试）。

<CardGroup cols={1}>
  <Card title="查看：上游错误" icon="list" href="/cn/api-reference/introduction/errors/upstream">
    上游错误的特点、典型场景与排查建议。
  </Card>
</CardGroup>

## 2. 系统级错误（System）

系统级错误由平台自身产生，通常与账户状态、令牌状态、配额与权限有关，例如：

* 账户余额不足
* 令牌过期 / 被禁用
* 访问受限（权限不足、策略拦截等）

这类错误会返回 **固定的 JSON 错误格式**，并在 `error.source` 中标记来源为 `system`。

示例：

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "error": {
    "message": "Token is expired.",
    "type": "forbidden",
    "source": "system",
    "details": {
      "request_id": "2026010914011404810445",
      "note": "This error was generated by the system, not from any upstream provider."
    }
  }
}
```

<CardGroup cols={1}>
  <Card title="查看：系统级错误" icon="list" href="/cn/api-reference/introduction/errors/system">
    系统级错误的固定响应结构与常见原因。
  </Card>
</CardGroup>

## 3. 非格式化错误（Unformatted）

还有一类错误发生在「客户端 ↔ 系统」的通信链路中。这类错误通常**不会**返回规范的 JSON，常见形态包括：

* 纯文本错误
* HTML 错误页面（例如 CDN 超时页）

典型例子：当请求经过 CDN 且触发 120 秒强制超时时，客户端可能收到一个 HTML 页面，而不是 JSON。

<CardGroup cols={1}>
  <Card title="查看：非格式化错误" icon="list" href="/cn/api-reference/introduction/errors/unformatted">
    如何识别链路错误，以及如何处理超时/网关页面等非 JSON 响应。
  </Card>
</CardGroup>

## 非 200 响应头

只要系统返回格式化响应体，且响应码 **非 200**，响应头里都会包含以下字段：

* `Poixe-Error-Source`：错误来源标识（`system` 或 `upstream`）
* `Poixe-Request-Id`：请求 ID（用于排查与定位）

示例：

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
Poixe-Error-Source: system
Poixe-Request-Id: 2026010914011404810445
```

当你遇到问题需要联系团队时，请优先提供 `Poixe-Request-Id`，这会显著提升排查效率。