Felo API PlatformFelo API Platform

指南

错误、限流与重试

读懂错误响应和限流响应头，安全重试并定位常见故障。

所有 Felo API 的错误响应都返回 JSON，包含稳定的错误码和 request ID。先看 HTTP 状态，再看 code，最后看 message。

错误结构

当前生产环境的响应使用 HTTP 状态码作为 status：

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}
字段含义
statusHTTP 状态码，在响应体中重复一次
code机器可读的错误码
message面向人的说明
request_id本次请求的标识；联系支持时请附上

部分较早的 endpoint 示例使用 status: "error" 和不同的错误码字符串。请根据 HTTP 状态和 code 分支处理，不要依赖 message 的具体措辞。

常见错误码

HTTPCode含义处理方式
400Endpoint 专属校验错误码参数缺失或无效修正请求；不要原样重试
401UNAUTHORIZEDAPI key 缺失、无效、过期或已撤销发送 Authorization: Bearer $FELO_API_KEY；已撤销则轮换 key
402INSUFFICIENT_CREDITS服务额度不足在 Console Billing 充值后重试
404Endpoint 专属模型、任务或路由不存在检查模型 ID、任务 ID 和 endpoint 路径
429RATE_LIMITED超过限流阈值等待 Retry-After 后重试
5xxCHAT_FAILED、*_FAILED、SERVICE_UNAVAILABLE上游或服务故障退避重试；持续出现时联系支持

各 endpoint 的参考文档会列出该 endpoint 专属的错误码。可以从 Chat API 错误码 或你所调用 endpoint 的文档开始。

Request ID

Felo 错误响应都包含 request_id。请把它和 endpoint、HTTP 状态、错误码、模型 ID、任务 ID 一起记录。不要记录完整 API key。

Model API 还接受可选的 X-Request-Id 请求头。发送后它会在响应中回显，便于把自有日志与请求对应起来。如果不发送，就使用响应返回的 request_id。

限流

/v2/chat 是唯一有公开且实际执行限流规则的 Felo endpoint：

  • 按 API key，1 分钟窗口。
  • 按用户，1 分钟窗口。
  • 按用户，1 小时窗口。

拥有有效付费 Felo 订阅（含企业订阅）的用户不受限制，响应中也不会出现 X-RateLimit-* 头。如果无法验证订阅状态，限制仍然生效。

响应头含义
X-RateLimit-Limit当前生效的最紧维度上限
X-RateLimit-Remaining三个维度中剩余额度最小值
X-RateLimit-Reset当前窗口重置的 Unix 时间戳（秒）
Retry-After429 时建议的等待秒数

其他 /v2/** endpoint 目前没有强制限流。Model API 请求仍可能被上游供应商限流，并表现为 429。

不要在代码里写死具体数值，请在每次响应中读取这些头。

重试策略

情况是否重试
400、401、402、404否。先修正请求、key 或余额。
429是，在 Retry-After 或 X-RateLimit-Reset 之后。
5xx、超时、连接重置是，使用指数退避并加入抖动。
流式响应中途断开仅当应用能接受重复生成时重试。

推荐流程：

  1. 只重试幂等或可安全重复的请求。
  2. 使用指数退避：从约 1 秒开始，每次翻倍，上限 30 秒。
  3. 加入随机抖动，避免客户端同时重试。
  4. 达到较小尝试次数后停止，并把错误暴露出来。
  5. 遇到 429 时优先遵循 Retry-After，而不是自己的重试节奏。

排查顺序

  1. 确认 key 存在且未被撤销。
  2. 用同一个 key 调用 GET /api/v1/models，确认鉴权可用。
  3. 向目标 endpoint 发送最小可用请求。
  4. 逐个加入流式、工具或大输入。
  5. 异步任务先查任务状态，再决定是否重新提交。

相关