認証・401・404・429

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

まず見るコマンド

sf auth show --json

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

• effectiveBaseUrl
• authMode
• oauth.tokenAvailable

401: 認証情報の問題

代表的な 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 --json

API key で直接 API を呼んでいる場合だけ、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 --json

この状態では CLI からの API 実行も同じ認証で失敗します。表示された email_hint と失敗したコマンドを別経路で共有してください。

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

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

よくある原因:

• Preview URL を使っている(JSON ではなく HTML が返ってくるのが典型症状)
• production をログインや認証情報なしで呼んでいる
• base URL が別環境を向いている
• company / filing / observation の ID が古い

対処:

sf login --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 は search、jobs、construction、signals です。この heavy-only daily count は他の endpoint には影響しません。

• POST /api/signal-foundry/search
• GET /api/signal-foundry/jobs
• GET /api/signal-foundry/construction
• GET /api/signal-foundry/companies/:company_id/signals

sf auth show --json

HTTP API を直接使う場合は、Retry-After header と、レスポンスの error.rate_limit.window / error.rate_limit.limit / error.rate_limit.remaining も見てください。どの窓で、いくつ中いくつ残っているかが返ります。

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、credit-consuming Signal read 200/day です。Pro は search 5,000/month、Company Card 10,000/month、credit-consuming Signal read 1,000/month です。Credit Pack は credit 残高を増やしますが、この product quota や RPM は増やしません。quota の正本は 請求 です。

このページにないエラー

• account_scope_conflict、filing_not_found、compare_target_not_found: API リファレンス のエラー表を見ます。
• credit_balance_insufficient、max_credits_*: クレジットと maxCredits の失敗 を見ます。

再発防止

• 本番ジョブと検証ジョブで API key を分ける
• 無駄な retry loop を減らす
• 会社解決前に Company Card を何度も呼ばない
• エージェントは sf login、直接の API 連携は用途ごとの key に分ける

現時点で含まれないもの

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