常见错误码
WOX API 常见错误码及解决方案
常见错误码
WOX API 常见错误码及解决方案
含义： 请求参数无效，服务器无法处理请求。
常见原因：
- 请求体格式无效
- 缺少必填参数
- 参数类型不正确
- 上下文长度超出模型限制
- 第三方工具传入的参数格式不兼容
- 视频生成参数不正确
- 与 Codex 等工具的请求格式不兼容
解决方案：
- 检查是否包含所有必填参数
- 验证 JSON 格式是否有效
- 压缩提示词和对话历史
- 开始新对话重试
- 检查视频生成参数，如 FPS、时长、分辨率和宽高比
- 使用 Codex 等第三方工具时，检查并调整请求格式，或尝试其他 Agent
含义： 认证失败。请求未通过身份验证。
常见原因：
- API Key 不正确
- API Key 已过期
- API Key 配置不正确
- 请求 Header 中缺少 Authorization 字段
- API Key 属于其他账户
解决方案：
- 检查 API Key 是否复制完整
- 确认 API Key 仍然有效
- 重新生成 API Key 并重试
- 检查请求 Header 中是否正确包含 API Key
- 确认 API Key 属于当前使用的账户
含义： 账户余额或可用配额不足以完成请求。
常见原因：
- 账户余额不足
- Token Plan 配额不足
- 当前请求超出可用配额
- 订阅状态异常
- 充值或订阅尚未生效
解决方案：
- 检查账户余额
- 检查 Token Plan 或订阅状态
- 充值或升级套餐
- 降低单个请求的成本，例如缩短上下文或降低图像/视频生成规格
- 等待充值或订阅生效后重试
含义： 当前账户或 API Key 无权访问请求的资源。
常见原因：
- API Key 没有访问请求模型的权限
- 账户未被授予访问请求模型的权限
- 订阅、用户分组或权限状态尚未生效
- 请求来源被安全规则阻止
- IP 地址、地区或网络环境受到限制
解决方案：
- 检查账户是否有权限访问该模型
- 检查 API Key 是否属于正确的账户
- 确认订阅、用户分组或权限状态是否已生效
- 尝试使用其他网络环境
- 如果确认有权限但问题仍然存在，请联系技术支持
含义： 请求的 API 地址、路径或资源不存在。
常见原因：
- API 地址不正确
- Base URL 配置不正确
- 请求路径不正确
/v1被第三方工具重复添加- 模型名称不正确
- 请求的资源不存在
解决方案：
- 检查 API 地址是否正确
- 检查 Base URL 是否正确
- 检查第三方工具配置中
/v1是否被重复添加 - 检查模型名称是否正确
- 检查 API 路径是否遵循文档说明
含义： 当前 API 端点不支持正在使用的请求方法。
常见原因：
- HTTP 方法不正确
- 需要 POST 时使用了 GET
- 需要 GET 时使用了 POST
- 第三方工具中的请求方法配置不正确
解决方案：
- 查看 API 文档中所需的请求方法
- 确认端点使用正确的方法，如 GET 或 POST
- 更新第三方工具中的请求方法配置
- 修改请求方法后重试
含义： 请求超时。服务器无法在允许的时间内完成处理。
常见原因：
- 本地网络不稳定
- 请求内容过大
- 上下文过长
- 图像、视频或长文本任务处理时间过长
- 客户端超时设置过短
解决方案：
- 重试请求
- 检查本地网络环境
- 缩短输入内容或减少上下文长度
- 降低图像或视频生成规格
- 适当增加客户端超时设置
- 为长时间运行的任务添加重试逻辑
含义： 请求与当前资源或任务状态冲突。
常见原因：
- 重复提交任务
- 同一请求已在处理中
- 当前资源状态不允许此操作
- 第三方工具重复发送相同请求
解决方案：
- 避免在短时间内重复提交相同请求
- 等待当前任务完成后再重试
- 检查任务状态
- 在客户端添加重复提交保护
- 如果任务已完成，先检查任务历史
含义： 请求体过大，服务器无法处理。
常见原因：
- 请求体过大
- 输入上下文过长
- base64 图像过大
- 上传的文件或图像超出限制
- 单次请求提交的内容过多
解决方案：
- 压缩请求内容
- 减少上下文长度
- 分批提交内容
- 减小上传的图像大小或分辨率
- 对于图像，使用公共 URL 而不是发送大的 base64 数据
含义： 请求中的文件格式或 Content-Type 不受支持。
常见原因：
- 不支持上传的文件格式
- 请求 Header 中的 Content-Type 不正确
- 图像、音频或视频格式不符合 API 要求
- 第三方工具自动设置了不正确的 Content-Type
解决方案：
- 检查上传的文件格式
- 确认 Content-Type 是否正确
- 对于图像，使用 PNG、JPG、JPEG 或 WEBP 等常见格式
- 对于音频或视频，使用 API 支持的格式
- 转换文件格式后重试
含义： 请求格式有效，但参数值不符合模型或 API 要求。
常见原因：
- 参数值无效
- 图像编辑参数异常
- 视频生成参数异常
- seed、分辨率、宽高比、FPS 或其他参数超出允许范围
- 图生图请求中的图像 URL 无法访问
- base64 格式无效
- 图像或视频生成大小不符合要求约束
解决方案：
- 查看错误消息中的具体参数提示
- 检查图像或视频生成参数是否有效
- 检查 seed 值是否在允许范围内
- 检查图像 URL 是否可公开访问
- 检查 base64 内容是否完整有效
- 修改参数后重试
含义： 请求速率过高，超出当前账户的 RPM 限制。
常见原因：
- 超出 RPM 限制
- 账户或用户分组触发当前请求限制
- 并发请求过多
- 短时间内重复请求过多
- 自动重试频率过高
解决方案：
- 响应包含
Retry-After时按其等待，否则采用指数退避 - 降低请求频率
- 控制并发请求数量
- 添加合理的重试机制
- 避免短时间内重复请求
- 如需确认账户适用的限制，请联系平台支持
含义： 请求 Header 过大，服务器无法处理。
常见原因：
- Header 中包含的内容过多
- Authorization 信息异常
- Cookie 或自定义 Header 过大
- 第三方工具自动附加了过多 Header
解决方案：
- 减小请求 Header 大小
- 检查 Authorization 字段是否正确
- 移除不必要的 Cookie 或自定义 Header
- 在第三方工具中重新配置请求 Header
- 更新 Header 后重试
含义： 客户端在请求完成前关闭了连接。
常见原因：
- 客户端超时断开连接
- 浏览器或工具中断了请求
- 本地网络切换或断开
- 长时间运行的任务等待时间过长
- 第三方工具提前取消了请求
解决方案：
- 重新发送请求
- 检查本地网络稳定性
- 增加客户端超时设置
- 任务运行时避免关闭页面或中断工具
- 对于长时间运行的任务，使用异步任务或轮询
含义： 服务器遇到内部错误，或请求参数触发了服务异常。
常见原因：
- 请求参数异常
- 图像生成大小不符合要求
- 视频生成大小不符合要求
- OpenClaw 中未配置 context 参数
- 上游服务临时异常
解决方案：
- 检查请求参数
- 按所选模型的接口要求检查尺寸、时长和其他生成参数
- 检查 OpenClaw 设置中的 context 参数
- 修改参数后重试
- 如果多次重试后问题仍然存在，将错误详情提交给技术支持
含义： 网关或代理未能从上游服务收到有效响应。
常见原因：
- 本地网络问题
- DNS 解析问题
- 代理配置问题
- 网络连接不稳定
- 上游服务临时波动
解决方案：
- 检查本地网络环境
- 尝试其他网络
- 更改 DNS 设置
- 检查代理配置
- 稍后重试
- 必要时，请 AI 或技术人员协助检查本地网络配置
含义： 服务暂时不可用，或由于第三方工具配置问题导致请求失败。
常见原因：
- 模型名称不正确
- 获取模型列表失败
- 未选择回退模型
- 路由未启用
- 第三方工具实际上将请求发送到了错误的模型
- 服务暂时不可用
解决方案：
- 检查模型名称是否正确
- 重新获取模型列表
- 选择一个回退模型
- 启用路由
- 检查第三方工具中的测试模型和备份模型设置是否配置正确
- 稍后重试
含义： 网关等待上游服务响应时超时。
常见原因：
- 上游模型响应超时
- 图像、视频或长上下文任务处理时间过长
- 网络连接不稳定
- 高峰时段服务负载高
- 请求复杂度过高
解决方案：
- 稍后重试
- 缩短输入内容
- 降低图像或视频生成规格
- 减少并发请求
- 适当增加客户端超时设置
- 为长时间运行的任务添加重试逻辑
含义： 未知错误，通常与网络连接、网关行为或上游服务临时波动有关。
常见原因：
- 网络连接问题
- 上游服务临时波动
- 代理配置问题
- DNS 配置问题
- 网关返回了非标准错误
解决方案：
- 重试请求
- 检查本地网络环境
- 检查代理配置
- 检查 DNS 配置
- 稍后重试
- 如果问题持续存在，将完整错误消息提交给技术支持
含义： 网关连接上游服务时超时。
常见原因：
- 网络连接超时
- 网关到上游的连接问题
- 本地网络问题
- 代理配置问题
- DNS 配置问题
解决方案：
- 重试请求
- 检查本地网络
- 检查代理配置
- 更改 DNS 设置
- 尝试使用其他网络环境
- 稍后重试
含义： 连接已建立，但上游服务处理请求时间过长。
常见原因：
- 长上下文任务耗时过长
- 图像生成任务耗时过长
- 视频生成任务耗时过长
- 服务负载高
- 请求复杂度过高
解决方案：
- 稍后重试
- 降低请求复杂度
- 缩短上下文
- 降低生成规格
- 减少并发请求
- 对于长时间运行的任务，使用异步任务或轮询