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

# 错误处理

> 处理常见 HTTP 错误、限流和服务端故障。

先检查 HTTP 状态码，再读取响应体中的错误消息。不同模型供应商的错误对象可能略有不同。

| 状态码         | 含义          | 建议                              |
| ----------- | ----------- | ------------------------------- |
| `400`       | 请求参数无效      | 根据接口定义检查必填字段、字段类型和模型名称          |
| `401`       | 认证失败        | 检查 `Authorization` 请求头和 API Key |
| `403`       | 没有访问权限      | 检查账户权限、模型权限或内容策略                |
| `404`       | 路径、模型或任务不存在 | 检查 Base URL、接口路径、模型 ID 和任务 ID   |
| `413`       | 请求体过大       | 压缩上传文件、降低 Base64 数据大小或减少请求内容    |
| `429`       | 请求过多或额度不足   | 检查余额与限额，并使用指数退避重试               |
| `500`–`599` | 服务或上游模型暂时异常 | 对幂等请求执行有限次数重试                   |

## 重试原则

* 不要自动重试参数错误、认证错误或过大的请求体。
* 对 `429`、`502`、`503` 和 `504` 使用指数退避与随机抖动。
* 重试创建任务前，确认接口是否支持幂等，避免重复计费或创建重复任务。
* 在日志中记录请求 ID、HTTP 状态码、模型名称和错误消息，但不要记录 API Key。

```javascript theme={null}
const retryable = new Set([429, 502, 503, 504]);

if (retryable.has(response.status)) {
  // 使用指数退避后重试，并设置最大重试次数。
}
```