# 计费与错误处理

了解平台余额、计费单位、PPT 按页结算和重试规则。

本页适用于 `/api/v1/data/*` 下的 Felo OpenAPI 平台专属接口。调用使用**平台余额**，即以美元计价的服务额度，不消耗 Felo Pro 积分。原 `/v2` [Felo APIs](https://openapi.felo.ai/zh-CN/docs/api-reference/felo-apis.md) 使用 Pro 积分。

## 查看当前价格

```bash
curl -sS https://openapi.felo.ai/api/v1/data/prices
```

此公开接口无需密钥。按操作 ID 查找条目，读取当前单价和计费单位。不要假设所有接口价格相同，也不要把文档示例中的价格写死在应用里。

| 操作 ID | 计费单位 |
|---|---|
| `web.search`、`web.read`、`chat` | 请求 |
| `x.user.info`、`x.user.search`、`x.user.tweets`、`x.tweet.search`、`x.tweet.replies` | 返回结果条数 |
| `ppt.generate` | 实际生成页数 |
| `ppt.export` | 导出请求 |
| `ppt.generate.status`、`ppt.generate.historical`、`ppt.export.status`、`ppt.delete` | 不新增费用 |

查询状态免费不代表生成或导出免费。X 接口翻页以及返回的嵌套记录，可能增加计费量。

## 余额与预留费用

执行前，服务可能先预留本次操作所需余额。成功后结算，确认失败后释放预留。异步任务返回 ID 时，并不代表费用已完成最终结算。

PPT 按页定价时，创建先预留十页费用；生成成功后按实际产出结算，多余预留会释放。生成和导出分别计费。重复导出的行为见 [PPT 完整流程](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-ppt.md)。

执行结果或结算状态不确定时，预留可能继续保留，等待服务核对。不要把所有超时或 5xx 都理解为“没有执行、没有费用”，也不要立即重复提交付费操作。

在[控制台 Billing](https://openapi.felo.ai/console/billing)查看可用余额和用量。账户充值说明见[计费与额度](https://openapi.felo.ai/zh-CN/docs/faq/billing-and-credits.md)。

## 通过 API 查询钱包用量

账户所有者可以使用 **Felo 登录 token** 查询钱包调用记录。这里的认证凭据与调用 Data API 的 API Key 不同，不能直接使用 `FELO_API_KEY`。

```bash
curl -sS 'https://openapi.felo.ai/api/wallet/usage?call_type=data' \
  -H 'Authorization: Bearer YOUR_FELO_LOGIN_TOKEN'
```

记录列表位于 `data.items`，`call_type=data` 用于筛选能力调用。结合账户当前价格与实际用量核对费用；查询记录不等于发起新的生成任务。需要人工查看或充值时，仍可使用控制台 Billing。

## 正确读取错误

先检查 HTTP 状态。错误可能使用以下任一种结构，下面的值仅为示例：

```json
{"error":{"code":"invalid_parameter","message":"Check the request fields"},"request_id":"example-request-id"}
```

```json
{"status":402,"code":"INSUFFICIENT_BALANCE","message":"Insufficient balance","request_id":"example-request-id"}
```

优先读取 `error.code`、`error.message`，不存在时读取根层级的 `code`、`message`。返回 `request_id` 时请保留。成功响应则按具体接口解析，不能强制套用同一个错误格式或 `data` 外层。

## 按错误采取下一步

| HTTP 状态 | 常见原因 | 处理方式 |
|---|---|---|
| 400 | 缺少参数或参数非法 | 修正请求后再试 |
| 401 | 密钥缺失、无效、撤销或过期 | 检查密钥与认证头 |
| 402 | 平台余额不足 | 查看可用余额与预留费用，按需充值 |
| 404 | 资源不存在或不属于当前账户 | 检查 ID 和创建账户 |
| 409 | 与任务当前状态冲突，或执行结果待确认 | 读取错误码并查询已有任务，不要立即重复创建 |
| 410 | 资源已过期或删除 | 使用已保存的文件；确有需要时再创建任务 |
| 429 | 触发限流或 API Key 配额已用完 | 查看重置信息，降低频率或等待配额恢复 |
| 502 / 503 / 504 | 上游、服务可用性、超时或结算问题 | 重试付费操作前，先确认是否已有执行结果 |

`execution_unconfirmed`（409）与 `billing_settlement_pending`（503）需要特别处理：不要立即重提付费操作，先查询已知任务，或携带请求 ID 联系支持。HTTP 成功但返回空结果，与错误响应也要分开处理。

## 避免重试产生重复任务

- 查询任务或导出状态时，使用有上限的退避重试；返回 `Retry-After` 时遵循它。
- 创建请求失败但已经拿到 `task_id` 时，先查询该任务，不要再创建。
- 连接在收到 ID 前断开，执行结果可能不确定。不能假设重发请求会自动去重。
- 遇到 429，区分短期限流与 API Key 配额窗口；不断重试不能恢复配额。
- 达到设定等待期限后停止重试，向调用方展示可处理的错误。

联系支持时提供接口、发生时间、HTTP 状态和请求 ID，不要提供完整 API Key。