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

# 故障排查

> 常见错误与解决方案

## 认证错误

### 401 Unauthorized

**原因**：Token 无效或格式错误

**解决**：

```bash theme={null}
# 正确格式
curl -H "Authorization: Bearer $TOKEN" ...
```

检查：

* Token 是否正确复制（无多余空格）
* Token 是否已过期
* Token 是否有对应模型的访问权限

### 403 Forbidden

**原因**：Token 无权访问该模型或功能

**解决**：在控制台检查 Token 的模型权限配置

## 请求错误

### 400 Bad Request

**常见原因**：

1. **对话接口**：`messages` 格式错误
   ```json theme={null}
   // 正确
   {"messages": [{"role": "user", "content": "你好"}]}

   // 错误
   {"messages": [{"content": "你好"}]}  // 缺少 role
   ```

2. **图像接口**：`size` 格式不支持
   ```json theme={null}
   // 支持的尺寸
   "1024x1024", "1792x1024", "1024x1792"
   ```

3. **视频接口**：`seconds` 需为字符串
   ```json theme={null}
   // 正确
   {"seconds": "6"}

   // 错误
   {"seconds": 6}
   ```

### 422 Unprocessable Entity

**原因**：

* 提示词触发安全过滤
* 模型不支持请求的功能

**解决**：调整提示词内容，或确认模型支持该功能

## 速率限制

### 429 Too Many Requests

**解决**：

* 实现指数退避重试
* 在控制台查看配额
* 联系管理员提升限额

```python theme={null}
import time
import random

def retry_with_backoff(func, max_retries=5):
    for i in range(max_retries):
        try:
            return func()
        except Exception as e:
            if "429" in str(e):
                time.sleep((2 ** i) + random.random())
            else:
                raise
```

## 视频任务

### 任务长时间未完成

视频生成通常需要 1-5 分钟，建议：

* 轮询间隔 6-10 秒
* 设置超时 5-10 分钟
* 检查任务状态是否为 `failed`

### 视频下载失败

**原因**：URL 过期或网络问题

**解决**：

* 重新查询任务获取最新 URL
* 使用 `curl -L` 跟随重定向

## 模型错误

### Model not found

**原因**：模型名称错误或不可用

**解决**：

* 检查模型名称拼写
* 在控制台确认模型已启用
* 查看可用模型列表

## 最佳实践

1. **错误重试**：对 429、500 等临时错误使用指数退避
2. **超时设置**：对话 30 秒，视频 5-10 分钟
3. **日志记录**：保存请求 ID 便于排查
4. **测试验证**：新功能先在测试环境验证