preview と save の失敗

会社群を保存する時は、list create -> list refine -> list save -> export の順に進みます。 preview は無料です。保存済みリストを作る時だけ クレジット上限を明示します。

正常な流れ

sf list create "上場企業のうち、売上100億以上" --json
sf list refine <listId> "東証プライムだけ" --json
sf list save <listId> --max-credits <estimatedCredits> --json
sf list export <listId> --format csv --output ./exports/list.csv --json

見る key:

• list.list_id
• list.status
• list.row_count
• rows[]
• actions[]
• gaps[]
• cost.save_estimated_credits
• billing.credits_used

preview_export_not_allowed

preview は確認用です。保存済みリストではないため、直接 export できません。

復旧:

sf list save <listId> --max-credits <estimatedCredits> --json
sf list export <listId> --format csv --output ./exports/list.csv --json

export は 保存済みリストに対する無料操作です。

unsupported / gaps

gaps は 0 件成功として扱わないでください。保存前に条件を分けるか、人間に確認します。

sf list refine <listId> "対応できる条件だけ" --json

判断:

max_credits_exceeded

保存に必要な クレジットが上限を超えています。

復旧:

sf list refine <listId> "さらに狭い条件" --json
sf list save <listId> --max-credits <newLimit> --json

クレジット残量が不明な場合:

sf credits balance --json

idempotency

list save は クレジットを使う書き込みです。CLI は idempotency key を付けて二重消費を避けます。

API で直接実行する場合は、書き込み request に Idempotency-Key header を付けます。CLI の通常利用では、まず sf list save ... --json と sf list show <listId> --json で状態を確認してください。

まだ保存しない判断

次の場合は list save に進みません。

• list.row_count が大きすぎて クレジット上限が決められない
• gaps[] が残っている
• ユーザーが --max-credits の上限を明示していない
• preview だけで十分で、保存済みリストが不要

保存すると 行が固定され、クレジットが消費されます。不確かな条件は先に list refine に戻してください。