トラブルシューティング

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

症状別の表

認証

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

{
  "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 の作成と制限は認証を参照してください。

Base URL の落とし穴

よくある 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 はモデルページまたは GET /api/v1/models で確認します。
• モデルが呼び出すプロトコルに対応しているか（supported_protocols）を確認します。
• チャネルを固定した場合は、そのチャネルがモデルに対して公開され実行可能か確認します。利用不可のチャネルはフォールバックではありません。

チャネルとプロバイダールーティングを参照してください。

ストリーミングの問題

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

非同期タスクの問題

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

非同期タスクを参照してください。

Data API の問題

• Data API reference の正確な 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 全体は含めないでください。

関連

• エラー、レート制限、リトライ
• プロトコルと SDK
• 課金とクレジット
• 認証