# OpenAPI の課金とエラー

プラットフォーム残高、リクエストおよび結果の課金、ページ課金、安全なリトライを理解します。

このページは `/api/v1/data/*`、つまり Felo OpenAPI のプラットフォーム専用 API に適用されます。呼び出しには **プラットフォーム残高**、つまり USD 建てのサービスクレジット残高が使用されます。Felo Pro クレジットは消費しません。旧来の [Felo APIs](https://openapi.felo.ai/ja/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/ja/docs/data-api/guides/felo-ppt.md) を参照してください。

実行または精算が不確実な場合、サービスが調整している間、予約が保留のまま残ることがあります。すべてのタイムアウトや 5xx を「作業が行われていない」または「再送が無料である」ことの証拠として扱わないでください。

利用可能残高と使用状況は [Console Billing](https://openapi.felo.ai/console/billing) で確認してください。アカウントレベルのチャージ案内については [Billing and Credits](https://openapi.felo.ai/ja/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）には特別な注意が必要です。課金対象の作業をすぐに再送信しないでください。既知のタスクを問い合わせるか、リクエスト ID とともにサポートへ連絡してください。成功した HTTP ステータスで空の結果が返ることは、エラー応答とは異なります。

## 重複作業を作らずに再試行する

- 読み取り専用のタスク照会や export-status 照会では、バックオフを制限し、`Retry-After` がある場合はそれに従ってください。
- 保存済みの `task_id` を使って失敗した作成リクエストがある場合は、新しいタスクを作成する前にそのタスクを問い合わせてください。
- ID を受け取る前に接続が失敗した場合、結果は不明かもしれません。再送するとリクエストが重複排除されると仮定しないでください。
- 429 では、短いレート制限と API キーのクォータウィンドウを区別してください。繰り返し再試行してもクォータはリセットされません。
- 設定した期限を超えたら再試行を停止し、呼び出し元に実行可能なエラーを表示してください。

サポートには、エンドポイント、おおよその時刻、HTTP ステータス、リクエスト ID を提供してください。API キー全文は絶対に含めないでください。