# トラブルシューティング

認証、モデル、streaming、タスク、レート制限の問題を症状から切り分けます。

症状から始め、修正手順に従ってください。失敗の多くは base URL、key、モデル ID、残高のいずれかに起因します。

## 必要なモデルが見つからない場合は？

[support@felo.ai](mailto:support@felo.ai) までお問い合わせください。一部のモデルは特定のお客様のみに提供しており、公開カタログに表示されない場合があります。必要なモデルが掲載されていない場合は、利用について直接ご相談ください。

## 症状別の表

| 症状 | 考えられる原因 | 修正 |
|---------|--------------|-----|
| 401 `UNAUTHORIZED` | key がない、誤っている、失効している、または送っていない | `Authorization: Bearer $FELO_API_KEY` を送る。失効している場合は新しい key を作る |
| 402 `INSUFFICIENT_CREDITS` | 残高が呼び出しに足りない | [Console Billing](https://openapi.felo.ai/console/billing) でチャージする |
| すべてのリクエストで 404 | base URL に endpoint が既に付けるパスを含めている | OpenAI クライアントは `https://openapi.felo.ai/api/v1`、Anthropic クライアントは `https://openapi.felo.ai/api` |
| 1 つのモデルだけ 404 | モデル ID が公開されていない、または endpoint がそのモデルを提供していない | [モデルページ](https://openapi.felo.ai/ja/models)と endpoint のドキュメントでモデル ID を確認する |
| 400 `model` または `max_tokens` エラー | 必須フィールドの欠落、またはモデルがリクエスト形式を受け付けない | Messages には `max_tokens` を追加する。未対応のフィールドを削除する |
| 429 | レート制限、または上流プロバイダーの制限 | `Retry-After` を読む。[エラー、レート制限、リトライ](https://openapi.felo.ai/ja/docs/guides/errors-and-limits.md)を参照 |
| 5xx | 上流またはサービスの障害 | バックオフ付きで再試行する。続く場合は `request_id` を添える |
| ストリームは接続するが何も送られない | プロキシがレスポンスをバッファリングしている、またはパーサーが誤った形式を期待している | ストリームを逐次読む。プロキシのレスポンスバッファリングを無効にする |
| タスクが終わらない | ポーリング先の endpoint が違う、または終端ステータスを処理していない | タスク自身のステータス endpoint をポーリングし、終端値で停止する |
| ツール呼び出しが無視される | モデルがその機能を提供していない | カタログの `supported_parameters` を確認する |
| Data API が 404 を返す | `/v1/beta` プレフィックスを二重に付けている | リファレンスに書かれたパスをそのまま使う |

## 認証

失効した key は、key のプレフィックスを含むメッセージを返します。

```json
{
  "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 は再表示できません。新しい key を作成してください。

key の作成と制限は[認証](https://openapi.felo.ai/ja/docs/authentication.md)を参照してください。

## Base URL の落とし穴

| クライアント | 正しい base URL |
|--------|------------------|
| OpenAI SDK | `https://openapi.felo.ai/api/v1` |
| Anthropic SDK | `https://openapi.felo.ai/api` |
| 直接のモデル endpoint | `https://openapi.felo.ai/api/v1/chat/completions`、`/responses`、`/messages` |
| Data API | `https://openapi.felo.ai/v1/beta` |
| Felo `/v2` APIs | `https://openapi.felo.ai/v2` |

よくある 2 つの誤り:

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 であり、上流プロバイダーの内部名や表示名ではありません。

- ID は[モデルページ](https://openapi.felo.ai/ja/models)または `GET /api/v1/models` で確認します。
- モデルが呼び出すプロトコルに対応しているか（`supported_protocols`）を確認します。
- チャネルを固定した場合は、そのチャネルがモデルに対して公開され実行可能か確認します。利用不可のチャネルはフォールバックではありません。

[同じモデルでも料金が違うのはなぜ？](https://openapi.felo.ai/ja/docs/guides/provider-routing.md)を参照してください。

## ストリーミングの問題

- `stream: true` はリクエストボディで設定し、query パラメータにはしないでください。
- レスポンスボディをストリームとして読みます。全体を待つとストリーミングの意味がありません。
- 一部のプロキシやサーバーレスプラットフォームはレスポンスをバッファリングします。リクエストを中継するルートでバッファリングを無効にします。
- Chat Completions がストリームするのは `choices[0].delta` で、`choices[0].message` ではありません。最終的な内容は多くの chunk に分かれて届きます。
- 接続が切れると、きれいな終端イベントなしでストリームが終わることがあります。切断は不完全なレスポンスとして扱ってください。

## 非同期タスクの問題

- タスクの種類に対応するステータス endpoint をポーリングします。Felo ワークフローは `GET /v2/tasks/{task_id}/status`、モデルの動画・画像タスクはそれぞれの生成 endpoint です。
- 成功だけでなく、失敗や期限切れを含むすべての終端ステータスで停止します。
- 動画生成で callback フィールドを送ると `400` が返り、画像生成では無視されます。webhook を待たないでください。
- 結果 URL は短命な場合があります。ダウンロードが失効したらステータス endpoint から新しい URL を取得します。
- 再送信の前にタスクを確認します。実行中のタスクを再送信すると重複が生じ、両方に課金されます。

[非同期タスク](https://openapi.felo.ai/ja/docs/guides/async-tasks.md)を参照してください。

## Data API の問題

- [Data API reference](https://openapi.felo.ai/ja/docs/data-api) の正確な method パスを保ちます。
- リクエストボディはプロバイダー固有です。あるプロバイダーで動くフィールドが別のプロバイダーでも動くとは限りません。
- プロバイダーのエラーは、プロバイダー固有のメッセージを伴う 4xx として返ることがあります。`request_id` とレスポンスボディを記録してください。

## セキュリティの注意

- API key をブラウザのコード、モバイルアプリのバンドル、公開リポジトリに入れないでください。サーバーに置き、リクエストをプロキシします。
- key 全体をログに残さないでください。識別が必要ならプレフィックスを記録します。
- 漏洩の疑いがある場合は直ちに key をローテーションします。

## サポートに連絡する前に

次を集めてください。

1. endpoint と HTTP method。
2. HTTP ステータス、`code`、`request_id`。
3. モデル ID またはタスク ID。
4. タイムゾーン付きのタイムスタンプ。
5. 機密を除いた最小のリクエストボディ。

アカウントの email とともにサポートへ送ってください。API key 全体は含めないでください。

## 関連

- [エラー、レート制限、リトライ](https://openapi.felo.ai/ja/docs/guides/errors-and-limits.md)
- [プロトコルと SDK](https://openapi.felo.ai/ja/docs/guides/protocols.md)
- [課金とクレジット](https://openapi.felo.ai/ja/docs/faq/billing-and-credits.md)
- [認証](https://openapi.felo.ai/ja/docs/authentication.md)
