> ## 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；
* 确保 API Key 是最新有效的；
* 如使用环境变量或配置文件，请确认调用时已正确读取。

## 错误码 403

**描述**：权限不足。\
**解决方法**：

* 请确认当前 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` 字段；
* 然后查看控制台或日志的调用轨迹；
* 最终，如问题持续存在，请提交工单或联系技术支持获取帮助。