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

# 常见错误码说明

为了帮助用户更高效地排查和解决调用过程中遇到的问题，本文档整理了 PPIO API 平台常见错误码的定义、原因分析及处理建议。

## 错误码 400

**描述**：请求参数不正确。\
**解决方法**：\
请根据返回的错误信息提示，检查并调整请求参数格式、字段名称或取值范围，确保请求体符合 API 接口文档规范。

## 错误码 401

**描述**：API Key 鉴权失败，通常是密钥未设置、格式错误或已失效。\
**常见子类**：

* **未传入 API Key**：请求头缺少 `Authorization`，或未按 `Authorization: Bearer {API 密钥}` 的格式传入。
* **API Key 格式错误**：密钥应以 `sk_` 开头，检查是否被截断、混入空格或换行。
* **API Key 已删除或失效**：密钥在控制台被删除后立即失效，使用它的调用都会返回 401。请改用有效的密钥。
* **环境变量未正确读取**：如通过环境变量或配置文件传入，确认变量已设置且被正确加载。密钥的设置与排查参见[管理 API 密钥](/docs/support/api-key#环境变量配置)。

**解决方法**：

* 检查是否传入了正确的 API Key；
* 确保 API Key 是最新有效的；
* 如使用环境变量或配置文件，请确认调用时已正确读取，排查方法参见[管理 API 密钥](/docs/support/api-key#设置了变量但代码仍找不到)。

## 错误码 403

**描述**：权限不足。可能是账户没有调用该模型的权限，也可能是该 API Key 的模型访问范围不包含目标模型。\
**常见子类**：

* **账户权限不足**：当前 API Key 所绑定账户不具备调用该模型的权限。
* **未完成实名认证**：某些模型要求实名认证后才能使用。
* **密钥模型访问被限制**（错误码 `model_access_denied`）：该 API Key 配置了「模型访问」，目标模型不在其可访问范围内。此时请联系团队管理员调整该密钥的模型访问设置，详见[管理 API 密钥 — 模型访问](/docs/support/api-key#模型访问)。

**解决方法**：

* 请确认当前 API Key 所绑定账户是否具备调用该模型的权限；
* 如返回错误码 `model_access_denied`，说明该密钥的模型访问范围不包含目标模型，请联系团队管理员在[模型访问](/docs/support/api-key#模型访问)设置中放开该模型；
* 某些模型可能要求通过实名认证后才能使用：
  * 登录控制台查看账户的实名认证状态；
  * 若当前账户未实名，请先完成实名认证；
  * 如有其他已实名账户，请使用其下 API Key 发起请求。

## 错误码 429

**描述**：触发了 Rate Limit（调用频率限制）。\
**解决方法**：

* 根据错误信息，区分是 TPM（每分钟 Token 限制）还是 RPM（每分钟请求次数）被触发；
* 可参考平台的 Rate Limits 文档；
* 如需提升速率限制，请联系支持申请调整或使用认证账户发起请求。

## 错误码 503 / 504

**描述**：服务端超时或不可用，通常与系统负载或流控有关。

### 原因归因：

* 模型服务所在节点负载过高（GPU / CPU）；
* 非流式请求生成时间过长，超过网关（Nginx / API Gateway）的 timeout 配置；
* 下游依赖服务（如 Redis、模型引擎）不可用；
* 限流组件触发高峰保护策略，返回 503。

### 解决方法：

**用户侧建议：**

* **增加重试机制**：建议使用指数退避策略，避免短时间内重复压测；
* **改为流式请求**：Streaming 模式可边生成边返回 token，减少整体延迟，有效降低长文本生成失败率；
* **优化调用配置**：如通过自建代理调用，请确保 `client_timeout` 与 `proxy_timeout` 不低于 60 秒；
* **错峰调用**：如遇高并发场景，可稍后再尝试或避开高峰时段。

**服务端优化建议（供平台运营参考）：**

* 加强模型服务的负载监控与自动扩容机制；
* 网关层设置更合理的 `proxy_read_timeout`；
* 设计更精细的限流规则（如优先级队列、核心业务优先保活）；
* 搭配 Prometheus + Alertmanager 配置 503/504 异常告警。

## 错误码 500

**描述**：服务器内部错误，通常为后端服务异常或模型引擎崩溃。\
**解决方法**：

* 该类问题通常无法由用户自行解决，建议联系平台支持团队排查后端日志与资源状态；
* 同时可尝试更换请求模型或降级服务重试。

如遇其他未列明错误，建议：

* 首先参考 API 返回中的 `message` 字段；
* 然后查看控制台或日志的调用轨迹；
* 最终，如问题持续存在，请提交工单或联系技术支持获取帮助。