ガイド

エラー、レート制限、リトライ

エラー応答とレート制限ヘッダーを読み、安全に再試行し、よくある障害を特定します。

すべての Felo API は、安定したエラーコードと request ID を含む JSON のエラーボディを返します。まず HTTP ステータス、次に code、最後に message を読んでください。

エラーの封筒

現在の本番環境のレスポンスは、HTTP ステータスを status として返します。

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

フィールド	意味
`status`	HTTP ステータスコード（ボディにも同じ値）
`code`	機械可読なエラーコード
`message`	人が読むための説明
`request_id`	このリクエストの不透明な識別子。サポートに連絡する際に含めます

一部の古い endpoint の例では status: "error" と異なるコード文字列を使っています。message の正確な文言ではなく、HTTP ステータスと code で分岐してください。

HTTP	Code	意味	対処
400	Endpoint 固有の検証コード	パラメータの欠落または不正	リクエストを修正する。そのまま再試行しない
401	`UNAUTHORIZED`	API key の欠落、無効、期限切れ、失効	`Authorization: Bearer $FELO_API_KEY` を送る。失効している場合は key をローテーションする
402	`INSUFFICIENT_CREDITS`	サービス利用枠が不足	Console Billing でチャージしてから再試行
404	Endpoint 固有	不明なモデル、タスク、ルート	モデル ID やタスク ID、endpoint のパスを確認
429	`RATE_LIMITED`	レート制限に達した	`Retry-After` を待ってから再試行
5xx	`CHAT_FAILED`、`*_FAILED`、`SERVICE_UNAVAILABLE`	上流またはサービスの障害	バックオフ付きで再試行。続く場合はサポートに連絡

endpoint のリファレンスには、その endpoint 固有のコードが記載されています。Chat API のエラーか、呼び出す endpoint のリファレンスから始めてください。

Felo のエラーボディには request_id が含まれます。endpoint、HTTP ステータス、エラーコード、モデル ID、タスク ID と一緒に記録してください。API key 全体は決してログに残さないでください。

Model API は任意の X-Request-Id リクエストヘッダーも受け付けます。送ると診断用にエコーバックされるため、自分のログとリクエストを対応付けられます。送らない場合は返された request_id を使ってください。

/v2/chat は、ドキュメント化された強制レート制限がある唯一の Felo endpoint です。

有効な有料 Felo サブスクリプション（エンタープライズ含む）を持つユーザーは免除され、X-RateLimit-* ヘッダーを受け取りません。サブスクリプション状態を確認できない場合、制限は適用されます。

ヘッダー	意味
`X-RateLimit-Limit`	現在有効な最も厳しい次元の上限
`X-RateLimit-Remaining`	3 次元のうち残りの最小値
`X-RateLimit-Reset`	現在のウィンドウがリセットされる Unix タイムスタンプ（秒）
`Retry-After`	429 時の推奨待機秒数

その他の /v2/** endpoint には現在強制レート制限はありません。Model API のリクエストは上流プロバイダーによって制限され、429 として現れることがあります。

数値の上限をハードコードしないでください。各レスポンスのヘッダーを読んでください。

状況	再試行するか
400、401、402、404	しない。まずリクエスト、key、残高を修正する。
429	`Retry-After` または `X-RateLimit-Reset` の後に再試行する。
5xx、タイムアウト、接続リセット	指数バックオフと jitter を付けて再試行する。
ストリーミング中に接続が切れた	重複生成を許容できる場合のみ再試行する。

推奨するループ: