故障排查

先看症状，再按对应方式处理。多数失败来自 Base URL、key、模型 ID 或余额。

按症状排查

认证

被撤销的 key 会在 message 中带上 key 前缀：

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key has been revoked (keyPrefix=...)"
}

检查项：

• Model API 和 Felo APIs 使用 Authorization: Bearer <key>。
• Data API 也接受 X-API-Key: <key>。
• key 没有被引号包裹，也没有从环境变量复制时带上的尾部换行。
• 部署环境确实设置了这个变量；本地可用不代表生产已配置。
• key 没有被删除或轮换。已删除或轮换的 key 无法再次显示，只能新建。

key 的创建方式和限制见认证。

Base URL 陷阱

两个常见错误：

1. 在 SDK 已经会追加路径的 Base URL 后面又加了 /chat/completions。
2. 把 Anthropic Base URL 设成 https://openapi.felo.ai/api/v1。SDK 会追加 /v1/messages，请求就变成 /api/v1/v1/messages。

模型 ID 问题

模型 ID 是目录中的公开 ID，不是上游供应商的内部名称，也不是显示名称。

• 在模型页或 GET /api/v1/models 中确认 ID。
• 确认模型支持你正在使用的协议（supported_protocols）。
• 如果固定了渠道，确认该渠道对该模型已发布且可运行。不可用的渠道不会自动回退。

见渠道与供应商路由。

流式问题

• 在请求体中设置 stream: true，不要放在 query 参数里。
• 把响应体当作流读取。等完整响应返回就失去了流式的意义。
• 部分代理和 serverless 平台会缓冲响应。为转发该请求的路由关闭缓冲。
• Chat Completions 流式返回的是 choices[0].delta，不是 choices[0].message。最终内容会分布在多个 chunk 中。
• 连接中断时，流可能没有干净的终止事件。连接中断应视为未完成响应。

异步任务问题

• 轮询该任务类别对应的状态 endpoint。Felo 工作流用 GET /v2/tasks/{task_id}/status；模型视频和图片任务用各自的生成 endpoint。
• 在所有终态停止，包括失败和过期，而不只是成功。
• 视频和图片 callback 目前会被忽略，不要等待 webhook。
• 结果 URL 可能有效期很短。下载过期后，向状态 endpoint 重新获取。
• 重新提交前先查任务。对运行中的任务重复提交会创建副本，且两份都会计费。

见异步任务。

Data API 问题

• 使用 Data API 参考中的原始方法路径。
• 请求体因供应商而异。对一个供应商有效的字段，不保证对另一个有效。
• 供应商错误可能以 4xx 响应返回，message 中含供应商细节。记录 request_id 和响应体。

安全提醒

• 不要把 API key 放进浏览器代码、移动端安装包或公开仓库。把它放在服务端并代理请求。
• 不要记录完整 key。需要标识时只记录前缀。
• key 可能已泄露时，立即轮换。

联系支持前

请准备：

1. Endpoint 和 HTTP 方法。
2. HTTP 状态、code 和 request_id。
3. 模型 ID 或任务 ID。
4. 带时区的时间戳。
5. 去掉敏感值后的最小请求体。

连同账户邮箱一起发给支持。不要包含完整 API key。

相关

• 错误、限流与重试
• 协议与 SDK
• 计费与额度
• 认证