認証・401・404・429

401 404 429 は見た目が似ていますが、直し方はまったく違います。

まず見るコマンド

sf auth show --json

ここで最低限確認するのは次です。

• effectiveBaseUrl
• authMode
• oauth.tokenAvailable
• configPath

401: auth 認証情報 の問題

代表的な code:

• authentication_required
• invalid_oauth_token
• oauth_token_missing
• oauth_token_expired
• invalid_api_key
• api_key_revoked
• api_key_rotated
• api_key_expired

対処:

sf auth show --json
sf login --base-url https://signal-foundry.app --json

直接 API連携で API key を使っている場合だけ、key の rotate / revoke / expiry を確認してください。用途ごとに 認証情報 を分けている場合は、いまの job が参照している secret store / .env も確認してください。

古い API や一部の protected route は、認証なしのアクセスを 404 not_found として隠すことがあります。CLI の error.suggested_next_commands に sf auth show --json / sf login ... が出ている場合は、404 でも認証復旧を優先します。

403 oauth_email_not_allowed: WorkOS account の allowlist 問題

sf auth show --json で authMode: "oauth"、oauth.tokenAvailable: true でも、ログイン中のメールが API allowlist 対象外だと 403 oauth_email_not_allowed になります。

CLI は safe な診断として email_hint と email_domain を返します。許可済みメールでログインし直すか、管理者に allowlist 追加を依頼してください。

sf auth show --json
sf login --base-url https://signal-foundry.app --json

この状態では sf feedback create も同じ認証で失敗します。CLI から feedback を送れない場合は、表示された email_hint と失敗したコマンドを別経路で共有してください。

404: base URL、ID、または access model の問題

company_not_found ではなく、単に not_found が返るときは、接続先、認証、または古い ID がずれている可能性が高いです。

よくある原因:

• Preview URL を使っている
• production へ ログイン / 認証情報 なしで叩いている
• base URL が別環境を向いている
• company / filing / observation の ID が古い

対処:

sf login --base-url https://signal-foundry.app --json
sf auth show --json

429: レート制限

Signal Foundry は 認証情報 単位で request-based rate limit を適用します。 429 rate_limit_exceeded が出たら、まず待ってから再試行してください。

Company-first plan-aware limit は次です。

• Free API key: 120/min, rolling 10,000/day
• Pro API key: 300/min, rolling 10,000/day
• heavy endpoint: rolling 2,000/day

heavy endpoint は company search、jobs、construction、batch 系 API です。この heavy-only daily count は他の endpoint には影響しません。

• GET /api/signal-foundry/companies
• GET /api/signal-foundry/jobs
• GET /api/signal-foundry/construction
• POST /api/signal-foundry/companies/batch-resolve
• POST /api/signal-foundry/signals/batch

sf auth show --json

HTTP API を直接使うなら、Retry-After header も見てください。

curl -i -H 'x-api-key: <SIGNAL_FOUNDRY_API_KEY>' \
  'https://signal-foundry.app/api/signal-foundry/companies?q=7203&limit=1'

daily_search_quota_exceeded、monthly_card_quota_exceeded などの product quota error は、429 rate limit とは別です。CLI では usage error として返り、Retry-After ではなく sf usage --json の残りと quota error の error.reset_at を見ます。

Free の product quota は search 1,000/day、Company Card 2,000/day、deep signal 200/day です。Pro は search 5,000/month、Company Card 10,000/month、deep signal 1,000/month です。Credit Pack は credit 残高を増やしますが、この product quota や RPM は増やしません。

再発防止

• 本番ジョブと検証ジョブで API key を分ける
• 無駄な retry loop を減らす
• 会社解決前に profile を何度も叩かない
• エージェントは sf login、直接 API連携 は用途ごとの key に分ける
• sf login は file token store が既定。SIGNAL_FOUNDRY_OAUTH_TOKEN_STORE=keychain を明示して oauth_keychain_unavailable が出る場合だけ OS keychain / secret-tool を確認する

まだ期待しないこと

external research の queue や保存状態を見てリトライ制御するような仕組みは、現時点の公開 product core ではありません。 今の前提は、base URL と ログイン / 認証情報 を正しく保ち、CLI の error hint に従って復旧することです。