错误码与排查
这篇文档帮助购买 API 的用户排查在使用 VLX FLUX 时遇到的常见错误，适用于 OpenAI 兼容 SDK、HTTP 请求、CLI 工具和第三方客户端。
快速检查清单
在查看具体错误码前，先确认：
- API Key 正确、有效，并且复制时没有多余空格。
- Base URL 是
https://api.vlxflux.io/v1。 - 请求路径正确，例如
/chat/completions或/models。 - 所选模型当前账号可以调用。
- 账户余额充足。
- 本地网络、代理或 DNS 设置正常。
常见 HTTP 错误
| 错误 | 含义 | 处理方式 |
|---|---|---|
400 Bad Request | 请求体或参数格式错误 | 检查 JSON 语法、必填字段和参数类型 |
401 Unauthorized | API Key 缺失、无效、被禁用或格式错误 | 检查 Authorization: Bearer YOUR_API_KEY 请求头 |
403 Forbidden | 当前 Key 无权调用该模型或分组 | 检查模型权限、分组权限和账号状态 |
404 Not Found | URL 或路径错误 | 确认 Base URL，避免重复 /v1 |
408 Request Timeout | 请求耗时过长 | 稍后重试，或降低请求复杂度 |
429 Too Many Requests | 触发频率、并发或额度限制 | 降低请求频率或并发数 |
500 Internal Server Error | 平台或上游异常 | 稍后重试，持续出现请联系支持 |
502 Bad Gateway | 上游模型返回异常 | 稍后重试，或切换模型 |
503 Service Unavailable | 服务或上游模型暂时不可用 | 稍后重试，或切换其他可用模型 |
504 Gateway Timeout | 上游模型响应超时 | 重试、减少上下文长度，或切换模型 |
鉴权问题
401 Unauthorized
通常由以下原因导致：
- 没有填写 API Key
- API Key 复制错误
- API Key 前后带有空格或换行
- API Key 已被禁用或删除
- 请求头没有包含
Bearer前缀
正确请求头：
http
Authorization: Bearer YOUR_API_KEY地址问题
404 Not Found
请确认客户端要求填写的是 Base URL 还是完整接口地址。
正确 Base URL：
text
https://api.vlxflux.io/v1正确聊天接口：
text
https://api.vlxflux.io/v1/chat/completions常见错误：
https://api.vlxflux.iohttps://api.vlxflux.io/v1/v1https://vlxflux.com- 把控制台网页地址当作 API 地址
模型问题
model not found
这通常表示模型名错误，或当前账号不可调用该模型。
请先查询模型列表：
bash
curl https://api.vlxflux.io/v1/models \
-H "Authorization: Bearer YOUR_API_KEY"然后使用接口返回或控制台展示的准确模型 ID。
403 Forbidden
模型可能存在，但当前 API Key 没有权限调用。请检查账号权限、余额和模型分组可用性。
计费问题
余额不足
如果账户余额不足，API 调用可能失败。请充值账户，或选择成本更低的模型。
你可以在控制台查看余额和消费记录。
消费高于预期
消费可能受以下因素影响：
- 输入 Token 长度
- 输出 Token 长度
- 模型基础价格
- 模型分组倍率
- 流式输出和重复重试
- 多个客户端共用同一个 API Key
如果消费高于预期，请先查看控制台消费记录。
限流问题
429 Too Many Requests
请降低请求频率或并发数。如果你在使用自动化任务，请增加带退避的重试逻辑。
例如：
- 重试前等待一段时间
- 限制并发请求数
- 减少长上下文请求
- 避免失败后立即无限重试
上游问题
部分模型依赖上游供应商。如果上游模型暂时不可用，可能出现 500、502、503 或 504。
建议处理方式：
- 稍后重试
- 切换到其他可用模型
- 减少上下文长度或输出长度
- 联系支持，并提供请求时间、模型名和错误信息
联系支持时提供什么
为了更快定位问题，请提供：
- 请求时间
- API 地址
- 模型名
- 错误码和错误信息
- 使用的是代码、CLI 还是第三方客户端
- 去除 API Key 后的请求示例
请不要在截图或支持消息中发送完整 API Key。