# OpenAPI 計費與錯誤

了解平台餘額、請求與結果費用、頁面計費以及安全重試。

本頁適用於 `/api/v1/data/*`，也就是 Felo OpenAPI 平台專屬 API。呼叫會使用 **平台餘額**，這是以 USD 計價的服務點數餘額。它們不會消耗 Felo Pro 點數。較早的 [Felo APIs](https://openapi.felo.ai/zh-TW/docs/api-reference/felo-apis.md) 位於 `/v2`，使用 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 頁面計價會在建立時預留 10 頁。成功生成會結算實際輸出並釋放未使用的資金。生成與匯出是分開計費的。請參閱 [PPT 工作流程](https://openapi.felo.ai/zh-TW/docs/data-api/guides/felo-ppt.md) 了解重複匯出的行為。

如果執行或結算結果不確定，預留金額可能會在服務進行對帳時維持待定。不要把每一次逾時或 5xx 都視為沒有任何工作發生，或重送請求就一定免費。

請在 [Console Billing](https://openapi.felo.ai/console/billing) 檢視你的可用餘額與用量。如需帳戶層級加值說明，請參閱 [Billing and Credits](https://openapi.felo.ai/zh-TW/docs/faq/billing-and-credits.md)。

## 透過 API 查詢錢包用量

帳戶擁有者可以使用 **Felo 登入權杖** 檢視錢包呼叫紀錄。這個憑證不同於 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` 會過濾能力呼叫。請將用量與帳戶目前價格比對。讀取紀錄不會提交另一個生成任務。Console 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 金鑰配額已超過 | 檢查重設資訊；降低頻率或等待配額重設 |
| 502 / 503 / 504 | 上游、可用性、逾時或結算失敗 | 在重試付費操作前，先確認工作是否已經存在 |

`execution_unconfirmed`（409）與 `billing_settlement_pending`（503）需要特別小心：不要立刻重新提交付費工作。請查詢已知任務或使用 request ID 聯絡支援。成功的 HTTP 狀態但回傳空結果，與錯誤回應不同。

## 在不產生重複工作的情況下重試

- 對於唯讀任務與匯出狀態查詢，請使用有上限的退避，並在有提供時遵守 `Retry-After`。
- 若建立請求失敗但你已有儲存的 `task_id`，請先查詢該任務，再建立另一個。
- 如果連線在你收到 ID 之前失敗，結果可能未知。不要假設重新送出就能自動去重。
- 對於 429，請區分短期速率限制與 API 金鑰配額視窗；反覆重試無法重設配額。
- 在你設定的截止時間後停止重試，並向呼叫端顯示可操作的錯誤。

如需支援，請提供端點、約略時間、HTTP 狀態與 request ID。切勿包含完整 API 金鑰。