故障排查
按错误码和现象定位 AsterMesh API、客户端和模型配置问题。
遇到问题时，不要同时改很多项。先用 curl 验证账号和 Key，再排查客户端。
快速自检
以下示例用于检查对话接口。视频生成的上传、任务状态和下载问题，见本页的 视频生成问题及 视频生成教程。
先运行：
curl https://console.astermesh.cn/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"如果这个请求失败，问题在账号、Key、网络或 AsterMesh 服务可用性。客户端配置先不要动。
如果这个请求成功，再测试模型：
curl https://console.astermesh.cn/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "MODEL_ID",
"messages": [
{
"role": "user",
"content": "ping"
}
]
}'错误码
| 错误 | 常见原因 | 处理方式 |
|---|---|---|
| 400 | 请求体格式错误、参数不支持 | 对照所用接口的最小示例检查；对话请求可只保留 model 和 messages，视频请求按视频教程核对 |
| 401 | API Key 错误或请求头错误 | 重新复制 Key，确认 Bearer 后有空格 |
| 403 | 无权限、账号状态异常 | 检查账号、模型权限、套餐状态 |
| 404 | Base URL 或 endpoint 写错 | Base URL 填 https://console.astermesh.cn/v1 |
| 408 | 请求超时 | 换快模型、减少输入、稍后重试 |
| 429 | 请求过快或触发限速 | 降低并发，开启退避重试 |
| 500 | 上游或网关内部错误 | 稍后重试，换模型验证 |
| 502/503/504 | 上游暂不可用或超时 | 换模型、稍后重试、减少上下文 |
401 Unauthorized
重点检查：
- Key 是否来自 AsterMesh 控制台。
- 是否把
sk-...复制完整。 Authorization是否写成Bearer YOUR_API_KEY。Bearer和 Key 中间是否有空格。- Key 前后是否多了引号或空格。
404 Not Found
最常见原因是 Base URL 填错。
客户端里应该填：
https://console.astermesh.cn/v1不要填：
https://console.astermesh.cn/v1/chat/completionsClaude Code 这类 Anthropic 客户端通常填：
https://console.astermesh.cn返回 HTML 网页，而不是 JSON 数据
如果调用模型列表等接口时，返回内容以 <!DOCTYPE html> 或 <html 开头，先检查请求地址是否误用了官网域名。API 请求应使用 console.astermesh.cn，例如 https://console.astermesh.cn/v1/models。
确认地址后再检查密钥。如果未携带有效 API Key，接口可能返回 401；按上面的「401 Unauthorized」步骤排查。
429 Too Many Requests
这通常不是 Key 错，而是请求太密集。
处理方式：
- 降低并发。
- 减少自动重试次数。
- 给重试加指数退避。
- 换一个限速更高或更轻量的模型。
- 检查 agent 是否进入循环。
模型不存在
如果看到：
model_not_found处理方式：
- 打开控制台模型列表。
- 复制完整模型 ID。
- 确认当前账号能使用该模型。
- 用
/v1/models验证列表里是否存在。
视频生成问题
视频接口按「上传素材 → 创建任务 → 查询状态 → 下载内容」使用，完整命令见 视频生成。
| 现象 | 检查方式 |
|---|---|
| 上传失败 | 检查本地图片路径和 API Key；上传命令使用 -F 表单，不要添加 JSON 请求头 |
| 创建请求被拒绝 | 对照 h3 示例检查 JSON、任务参数和参考图片 URL，保留上传结果中的真实素材地址 |
| 查询很久仍未完成 | 间隔查询同一个任务并设置等待上限；保留任务编号，稍后继续查询 |
| 查询结果表示生成失败 | 查看返回的失败原因，排查参数、素材或模型权限后再决定是否重新创建 |
| 下载失败 | 先确认 status 为 completed，再使用同一任务编号的 /content 地址，并保留 curl -L |
创建请求超时但已经取得任务编号时，先查询该任务。不要通过重复提交生成请求来检查进度。
客户端配置不生效
常见原因：
- GUI 设置和配置文件不是同一个入口。
- 终端没有重新打开，环境变量没生效。
- 工具读取的是
OPENAI_API_KEY，你设置的是ASTERMESH_API_KEY。 - 配置文件路径不对。
- 工具仍然使用官方 provider。
排查方式：
- 打印环境变量。
- 查看客户端启动日志。
- 临时改成一个明显错误的 Base URL，看错误是否变化。
- 如果错误不变，说明配置没有被读取。