---
url: /guide/faq/index.md
---
## 常见错误码说明

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

### 错误码 400

**描述**：请求参数不正确。

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

### 错误码 401

**描述**：API Key 设置不正确或未设置。

**解决方法**：

* 检查是否传入了正确的 API Key；
* 确保 API Key 是最新有效的；
* 如使用环境变量或配置文件，请确认调用时已正确读取。

### 错误码 403

**描述**：权限不足。

**解决方法**：

* 请确认当前 API Key 所绑定账户是否具备调用该模型的权限；
* 某些模型可能要求通过实名认证后才能使用：
  * 登录控制台查看账户的实名认证状态；
  * 若当前账户未实名，请先完成实名认证；
  * 如有其他已实名账户，请使用其下 API Key 发起请求。

### 错误码 429

**描述**：触发了 Rate Limit（调用频率限制）。

**解决方法**：

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

### 错误码 500

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

**解决方法**：

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

### 错误码 503 / 504

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

#### 原因归因

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

#### 解决方法

**用户侧建议**：

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

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

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

***

## 其他问题排查

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

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

## 错误码速查表

| 错误码 | 类型 | 描述 | 快速处理 |
|-------|------|------|---------|
| 400 | 客户端错误 | 请求参数不正确 | 检查请求参数格式 |
| 401 | 客户端错误 | API Key 无效 | 检查 API Key 配置 |
| 403 | 客户端错误 | 权限不足 | 检查账户权限/实名认证 |
| 429 | 客户端错误 | 频率限制触发 | 降低调用频率/申请提额 |
| 500 | 服务端错误 | 内部错误 | 联系技术支持 |
| 503 | 服务端错误 | 服务不可用 | 重试/改为流式请求 |
| 504 | 服务端错误 | 服务超时 | 重试/增加超时配置 |