トラブルシュート

estimate / materialize failure

`estimate_not_found` `preview_export_not_allowed`、weak / unsupported / needs_human、idempotency の復旧手順です。

このページの内容4項目

会社群を保存する時は、estimate -> candidates -> materialize -> export の順に進みます。 estimate と candidate preview は無料です。saved List を作る時だけ credit 上限付きで実行します。

正常な流れ

sf list estimate "上場企業のうち、売上100億以上" --json
sf list candidates --from-estimate <estimateId> --json
sf list materialize --from-estimate <estimateId> --name "売上100億以上の上場企業" --execute --max-credits <estimatedCredits> --json
sf list export <listId> --format csv --output ./exports/list.csv --json

見る key:

estimate.estimate_id
resolved_definition.status
resolved_definition.warnings
unsupported_conditions
weak_conditions
counts.matched_companies
billing.materialize.estimated_credits
meta.exportable
list.list_id
idempotency_key

`estimate_not_found`

estimate_not_found は、渡した estimateId が存在しない、期限切れ、または別 account / environment のものだった時に返ります。

復旧:

sf auth show --json
sf list estimate "上場企業のうち、売上100億以上" --json
sf list candidates --from-estimate <newEstimateId> --json
sf list materialize --from-estimate <newEstimateId> --name "売上100億以上の上場企業" --execute --max-credits <estimatedCredits> --json

sf auth show --json では effectiveBaseUrl と configPath を確認します。 preview URL や別 account の設定を使っている場合は、estimate から作り直してください。

`preview_export_not_allowed`

candidate preview は確認用です。 saved List ではないため、直接 export できません。

復旧:

sf list candidates --from-estimate <estimateId> --json
sf list materialize --from-estimate <estimateId> --name "<listName>" --execute --max-credits <estimatedCredits> --json
sf list export <listId> --format csv --output ./exports/list.csv --json

candidates の meta.exportable が false なら、先に materialize します。 export は保存済み List に対する無料操作です。

`weak` / `unsupported` / `needs_human`

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

sf data capabilities --json
sf list plan "生成AIに積極的な上場企業" --json
sf observations search "生成AI" --source edinet --json

判断:

状態	見る key	次の手
`weak`	`weak_conditions` / `resolved_definition.warnings`	evidence を確認し、条件を短くする
`unsupported`	`unsupported_conditions`	supported な条件に分解する。無理なら人間に確認
`needs_human`	`status` / `plan.conditions`	estimate に進まず、不足条件をユーザーへ返す

supported な条件に分解できたら、estimate に戻ります。

sf list estimate "上場企業 AND 情報・通信業" --json

idempotency

materialize は credit-consuming write です。 HTTP API では Idempotency-Key header が必須です。 CLI は再試行時の二重消費を避けるため、返ってきた idempotency_key を確認してください。

API で直接実行する例:

curl -s "$SIGNAL_FOUNDRY_BASE_URL/api/signal-foundry/lists/materialize" \
  -H "Authorization: Bearer <SIGNAL_FOUNDRY_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: list-materialize-20260501-001" \
  --data '{
    "estimateId": "est_123",
    "name": "売上100億以上の上場企業",
    "execute": true,
    "maxCredits": 42
  }'

idempotency_key_required が返る場合は、header を付けて同じ request を再実行します。 idempotency_conflict が返る場合は、同じ key を別 request に使っています。内容を変えた再実行では、新しい key を使ってください。

CLI で同じ job をやり直す場合は、まず保存済み List が作られていないか確認します。

sf list ls --json
sf list show <listId> --json

まだ保存しない判断

次の場合は materialize に進まないでください。

counts.matched_companies が期待より大きく、credit 上限が決められない
unsupported_conditions が残っている
weak_conditions を evidence で確認していない
ユーザーが maxCredits の上限を明示していない
candidate preview だけで十分で、saved List が不要

保存すると row が固定され、credit が消費されます。不確かな条件は先に query と source に戻してください。