トラブルシュート
トラブルシュート
Signal Foundry 利用時の典型エラーの分類と、症状別の復旧手順への導線です。
このページの内容4項目
Signal Foundry の失敗は、ほとんどが次の 4 種類に収まります。
company_not_foundと低ヒット検索: 低ヒット検索の見直し方- 認証の
401/403、接続先や access model を外した404、レート制限の429と product quota: 認証・接続・制限エラー - usage / credit の境界違反(
max_credits_required/max_credits_exceeded/credit_balance_insufficient): クレジットと maxCredits の失敗 needs_human: silent 0 件にせず、足りない条件をユーザーに確認します
CLI を使う場合は、まず次を実行して現在地を確認します。
sf --help --json sf version --json --check-update sf auth show --json sf search --help --json sf company --help --json sf credits summary --help --json
--json を付けると、失敗時に次の key が返ります。
error.codeerror.messageerror.hinterror.suggested_next_commands
Claude Code や Codex から使う場合は、エラー文を読むだけで止めず、error.suggested_next_commands の候補をそのまま実行します。
よくある復旧ルート
| 状況 | まず見るもの | 次にやること |
|---|---|---|
| CLI が古い / command がない | sf version --json --check-update | Homebrew または winget で sf を更新する |
company_not_found | sf search "<query>" --json | 低ヒット検索の見直し方 の手順で company_id を解決する |
| 自然文検索が 0 件 / 低ヒット | gaps[]、source_context、meta | 低ヒット検索の見直し方 で条件を短くし、分ける |
401 / 404 / 403 oauth_email_not_allowed | sf auth show --json | 認証・接続・制限エラー で認証と接続先を直す |
429 / quota error | sf usage --json | 認証・接続・制限エラー で rate limit と product quota を見分ける |
needs_human | gaps[] | silent 0 件にせず、足りない条件をユーザーに確認する |
max_credits_required / max_credits_exceeded | command help と usage estimate | クレジットと maxCredits の失敗 で対象会社数、signal、上限を揃える |
credit_balance_insufficient | sf credits balance --json | クレジットと maxCredits の失敗 で付与残高を確認してから再実行する |
| checkout できない | checkout / portal | plan、支払い方法、ブラウザのブロック設定を確認し、解決しなければ support に連絡する |
症状別ページ
- 認証・接続・制限エラー:
401403404429と product quota の見分け方と復旧 - 低ヒット検索の見直し方:
company_not_found、0 件、絞りすぎの見直し - クレジットと maxCredits の失敗:
max_credits_*とcredit_balance_insufficientの復旧
クレジットまわり
繰り返し検索や credit-consuming Signals の前に、usage とクレジットを確認します。
sf query --file company-query.json --json sf credits balance --json sf credits summary --json
財務しきい値は company_query.v1 に構造化してから sf query で実行します。Free は探索、Paid は volume と深い signals のために使います。クレジット失敗は クレジットと maxCredits の失敗 で復旧してください。
リストと CSV まわり
ユーザーが CSV や表を求める場合は、sf search の JSON から agent 側でローカルファイルを作れます。後で共有・再利用する会社群は、確定した company_id だけを sf list で Saved List に保存できます。
sf search "<criteria>" --limit 20 --json
会社が曖昧な場合は、法人番号、domain、ticker のどれかで再検索します。
sf list add の unknown_company_ids[] に値がある場合は、その ID を保存済みと扱いません。元の識別子で Search と Company Card を再確認し、解消しなければ人間へ戻します。持ち込み CSV の判定手順は 営業リストの名寄せ を見ます。