读懂聚合站返回的 HTTP 状态码：这个错到底是哪一层抛出来的

调用 LLM API 聚合站时，遇到错误返回是常有的事。但同样是 401 或 429，可能来自聚合站自身，也可能来自上游模型厂商。如果不区分来源，就可能查错方向、浪费时间。本文帮你按状态码归类，先定位问题层级，再动手解决。

为什么需要区分错误来源

聚合站作为中间层，会转发你的请求到上游厂商，同时也会在自身逻辑中抛出错误。两类错误的排查路径完全不同：

• 聚合站自身抛出的错误：通常与你的账户、API key、请求格式或聚合站的服务状态有关。
• 上游厂商转回来的错误：通常与所选模型的服务状态、配额或厂商侧限制有关。

快速区分二者，能让你直接找到正确的排查入口。

快速判断原则

一个简单的经验法则：

• 如果错误在请求到达上游之前发生（如认证失败、路由找不到、请求体解析失败），通常是聚合站抛出的。
• 如果错误是上游厂商返回后原样透传的，通常会在响应体中包含厂商的原始错误信息（如 OpenAI 的 error.type、Anthropic 的 error.type）。

你可以先看响应体的结构：聚合站自身的错误往往有统一的格式；上游透传的错误则保留厂商的原始结构。

按状态码分类

401 Unauthorized

通常来自聚合站自身。

聚合站需要验证你的 API key。如果 key 缺失、格式错误、已被禁用或余额不足，聚合站会直接返回 401，请求不会到达上游。

排查建议：

• 检查请求头中的 Authorization 字段是否正确携带了 API key。
• 确认 key 没有多余空格或换行。
• 登录聚合站控制台，检查 key 状态和账户余额。

少数情况下，如果聚合站使用上游厂商的 key 池，且所有 key 都失效，也可能返回 401，但此时响应体通常会指明是上游认证问题。

403 Forbidden

可能来自聚合站，也可能来自上游。

• 聚合站自身：你的账户被限制访问某个模型，或触发了聚合站的安全策略（如 IP 限制、地域限制）。
• 上游厂商：厂商对某些内容或行为有区域或政策限制，返回 403。此时响应体通常包含厂商的错误信息。

排查建议：先看响应体是否有厂商标识。如果有，查厂商文档；如果没有，查聚合站账户状态和访问策略。

404 Not Found

通常来自聚合站自身。

聚合站根据请求路径和模型名称路由到上游。如果路径错误或模型名称不在支持列表中，聚合站会返回 404。

排查建议：

• 核对请求的 endpoint 路径是否正确（如 /v1/chat/completions）。
• 确认请求的模型名称在聚合站支持的模型列表中。
• 注意模型名称大小写和拼写。

如果路径和模型都正确，但上游厂商返回 404（例如模型已下线），聚合站可能透传该错误，此时响应体会包含厂商信息。

422 Unprocessable Entity

通常来自聚合站自身。

422 表示请求格式正确但语义错误，常见于请求体参数不合法（如缺少必填字段、字段类型错误、参数值超出范围）。聚合站在转发前会做基础校验，不通过则直接返回 422。

排查建议：

• 检查请求体 JSON 是否符合 API 文档要求。
• 确认必填参数（如 model、messages）存在且类型正确。
• 检查参数值是否在允许范围内（如 temperature 的取值）。

少数上游厂商也可能返回 422，但通常聚合站会先拦截明显错误。

429 Too Many Requests

可能来自聚合站，也可能来自上游。

这是最容易混淆的状态码之一。

• 聚合站自身：你对聚合站的请求频率超过了聚合站设定的限制（如每分钟请求数、并发数）。
• 上游厂商：聚合站转发请求后，上游厂商因配额或速率限制返回 429，聚合站透传该错误。

排查建议：

• 查看响应头中的 Retry-After 或类似字段，以及响应体中的错误信息。
• 如果错误信息提到厂商名称或厂商特有的限制类型，则是上游返回。
• 如果错误信息是聚合站统一的限流提示，则是聚合站自身限制。
• 检查你的账户在聚合站上的配额使用情况，同时考虑所选模型在上游的配额状态。

500 Internal Server Error

可能来自聚合站，也可能来自上游。

500 表示服务器内部错误，范围较广。

• 聚合站自身：聚合站内部逻辑异常（如路由失败、数据库错误）。
• 上游厂商：厂商服务异常，聚合站透传 500。

排查建议：

• 查看响应体是否包含堆栈信息或厂商错误码。
• 如果错误可稳定复现且与特定模型相关，可能是上游问题。
• 如果所有模型都返回 500，可能是聚合站自身故障。
• 查看聚合站的状态页面或公告。

其他常见状态码

• 400 Bad Request：通常来自聚合站，表示请求格式错误（如 JSON 解析失败）。
• 402 Payment Required：通常来自聚合站，表示余额不足或需要充值。
• 503 Service Unavailable：可能来自聚合站（维护中）或上游（过载），需结合响应体判断。
• 504 Gateway Timeout：通常表示聚合站等待上游响应超时，问题可能在上游或网络链路。

实践建议

1. 始终记录完整响应：包括状态码、响应头和响应体，便于事后分析。
2. 在日志中标记错误来源：根据响应体特征，在应用层区分「聚合站错误」和「上游错误」，方便统计和告警。
3. 优先检查自身请求：401、403、404、422 大多与请求本身有关，先核对 API key、路径、模型名和请求体。
4. 关注响应体中的厂商信息：如果包含厂商原始错误结构，直接查阅厂商文档。
5. 利用聚合站的控制台和文档：聚合站通常会提供错误码说明和状态页面，遇到不确定的情况先查阅。

通过以上分类方法，你可以快速判断错误来源，避免在错误的层级上浪费时间。记住：先看响应体，再查对应层。