故障排除

接入与调用过程中的常见错误、原因与解决方案。

认证类错误

错误信息	HTTP 状态码	原因	解决方案
`invalid api key`	401	API Key 无效、已过期、被撤销或已禁用	前往控制台 → 令牌管理，确认令牌状态为可用；若已过期请重新创建并完整复制 sk- 开头的密钥
`invalid_api_key`	401	未提供 Authorization 头，或 Bearer Token 格式错误	请求头使用 Authorization: Bearer <API_KEY>，注意 Bearer 与密钥之间有一个空格
`forbidden`	403	令牌无权访问该模型或接口	在令牌管理中检查模型权限与分组；确认该模型对当前令牌已开放

路由与模型错误

错误信息	HTTP 状态码	原因	解决方案
`no model config found for: {model}`	404	请求的 model ID 不存在或未在网关配置	前往模型列表核对 model 拼写；使用 GET /v1/models 查看当前可用模型
`model field is required`	400	请求体缺少 model 字段	在 JSON 请求体中添加 "model": "gpt-4o" 等有效模型 ID
`invalid or empty requested model`	400	model 为空或格式非法	确认 model 为非空字符串，且与控制台模型 ID 完全一致（区分大小写）
`unknown api path`	404	API 路径错误或 Base URL 配置不正确	OpenAI 兼容接口 Base URL 应为 https://ai-api.easyapi.com/v1；对话补全路径为 /chat/completions

请求参数错误

错误信息	HTTP 状态码	原因	解决方案
`invalid_request_error`	400	请求 JSON 格式错误或字段类型不匹配	检查 Content-Type 为 application/json；对照 API 参考确认字段名与类型
`messages field is required`	400	Chat Completions 缺少 messages 数组	添加 messages: [{ "role": "user", "content": "..." }]
`max_tokens not supported`	400	部分新模型不支持 max_tokens 参数	改用 max_completion_tokens，或查阅该模型文档确认支持的参数字段
`prompt is required`	400	视频/图像生成请求缺少 prompt 或必填字段	对照视频/图片生成 API 参考补全 model、prompt 等必填项

配额与限流错误

错误信息	HTTP 状态码	原因	解决方案
`rate_limit_exceeded`	429	请求频率超过令牌或账户限流阈值	降低并发与 QPS；实施指数退避重试；必要时在控制台调整令牌限流配置
`quota exceeded`	429	令牌当日/当月配额已用尽	在令牌详情查看剩余配额；联系管理员提升限额或等待配额重置
`too many requests`	429	上游渠道或网关短时过载	间隔数秒后重试；避免突发大批量请求，可改用队列异步提交

计费与余额错误

错误信息	HTTP 状态码	原因	解决方案
`insufficient balance`	402	账户余额不足，无法完成扣费	前往控制台钱包充值；按量计费模型需保证余额大于单次预估费用
`insufficient_quota`	402	钱包额度或订阅剩余次数不足	查看使用记录与钱包余额；按次计费模型需确认剩余次数
`billing hard limit reached`	403	账户或令牌达到消费硬上限	在控制台调整消费上限，或联系管理员提升限额后重试

服务端内部错误

错误信息	HTTP 状态码	原因	解决方案
`server_error`	500	网关或上游服务内部异常	稍后重试；若持续出现，记录请求时间与 model，通过联系我们提交工单
`upstream error`	502	上游模型服务不可用或超时	切换备用模型或渠道；异步任务可稍后查询任务状态
`service unavailable`	503	服务维护或渠道暂时下线	查看站点公告；等待恢复后重试，或临时更换其他模型
`timeout`	504	请求处理超时（常见于长视频/大图生成）	视频生成改用异步任务接口并轮询状态；适当减小 prompt 复杂度或降低分辨率

常见场景速查

Base URL 错误

❌ https://ai-api.easyapi.com/chat/completions
✅ https://ai-api.easyapi.com/v1/chat/completions          # OpenAI 兼容对话
✅ https://ai-api.easyapi.com/v1/messages               # Claude 原生格式（Anthropic 兼容）

max_tokens 参数不兼容

❌ { "model": "gpt-4o", "max_tokens": 100 }
✅ { "model": "gpt-4o", "max_completion_tokens": 100 }  # 部分新模型需使用此字段

API Key 格式

❌ Authorization: sk-xxxxxxxx
✅ Authorization: Bearer sk-xxxxxxxxxxxxxxxx   # 注意 Bearer 前缀与空格

视频生成应使用异步流程

❌ 同步等待 POST /v1/chat/completions 直接返回视频（易超时）
✅ POST https://ai-api.easyapi.com/v1/videos → 轮询 GET /v1/videos/{job_id} → 下载 content 或 video_url

仍无法解决？

请通过联系我们提交工单，附上请求时间、模型 ID 与错误响应（勿泄露完整 API Key）。也可对照错误码说明与使用记录排查扣费与限流问题。