跳转到主要内容
Poixe AI 系统是一层 API 转发与调度层，因此错误大致分为三类。 理解这些分类有助于你更快定位问题、决定是否重试，以及在需要时向团队提供有效信息。

​
1. 上游错误（Upstream）

上游错误来自模型厂商或其网关。常见触发原因包括：
  • 请求体不符合协议（字段缺失、类型不匹配、参数非法等）
  • 鉴权失败（Key 无效、权限不足）
  • 上游限流、过载、服务异常
一般情况下，系统会尽量捕获常见上游错误，并根据错误类型判断是否需要自动重试（例如短暂的过载/限流可能会触发重试）。

查看：上游错误

上游错误的特点、典型场景与排查建议。

​
2. 系统级错误（System）

系统级错误由平台自身产生，通常与账户状态、令牌状态、配额与权限有关，例如：
  • 账户余额不足
  • 令牌过期 / 被禁用
  • 访问受限（权限不足、策略拦截等）
这类错误会返回 固定的 JSON 错误格式，并在 error.source 中标记来源为 system。 示例： 
{
  "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."
    }
  }
}

查看：系统级错误

系统级错误的固定响应结构与常见原因。

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

还有一类错误发生在「客户端 ↔ 系统」的通信链路中。这类错误通常不会返回规范的 JSON，常见形态包括：
  • 纯文本错误
  • HTML 错误页面（例如 CDN 超时页）
典型例子：当请求经过 CDN 且触发 120 秒强制超时时，客户端可能收到一个 HTML 页面，而不是 JSON。

查看：非格式化错误

如何识别链路错误，以及如何处理超时/网关页面等非 JSON 响应。

​
非 200 响应头

只要系统返回格式化响应体，且响应码 非 200，响应头里都会包含以下字段：
  • Poixe-Error-Source：错误来源标识（system 或 upstream）
  • Poixe-Request-Id：请求 ID（用于排查与定位）
示例： 
Poixe-Error-Source: system
Poixe-Request-Id: 2026010914011404810445
当你遇到问题需要联系团队时，请优先提供 Poixe-Request-Id，这会显著提升排查效率。