クレジットと maxCredits の失敗

クレジットを消費する実行は、必ず上限と残高を確認して進めます。 Company Search / Company Card の通常読み取りは軽い request credit ですが、深い signal、bulk、繰り返し実行では max_credits_required や credit_balance_insufficient が返ることがあります。

Plan quota と credit 残高は別です。Free / Pro の search、Company Card、deep signal の回数上限は sf usage --json で見ます。Credit Pack は credit 残高を増やしますが、plan quota、RPM、batch 上限、検索結果上限は増やしません。

まず見るコマンド

sf credits balance --json
sf credits summary --json
sf usage --json
sf query --file company-query.json --json

見る key:

• balance.available_credits
• balance.grants[]
• summary.usageBreakdown[]
• summary.recentEvents[]
• usage_limits.remaining
• quota error の error.reset_at
• meta.request_credit
• warnings[]
• gaps[]

エラーの見分け方

max_credits_required

max_credits_required は、実行上限を明示していない時に返ります。 エージェントは勝手に上限を決めず、command の help、返却された actions[]、usage estimate を確認してください。

sf <command> --help --json
sf credits balance --json
sf <command> ... --max-credits <estimatedCredits> --json

ユーザーが指定した予算がある場合は、その数字を超えて実行しないでください。

max_credits_exceeded

max_credits_exceeded は、実行に必要な クレジットが --max-credits を超えた時に返ります。 この場合、クレジットは消費されません。

対象を狭めても良いなら、検索条件や signal 範囲を削ります。

sf company search "東証プライムの上場企業で生成AIに関連" --json
sf company observations <companyId> --limit 5 --json

対象件数に納得しているなら、人間に確認してから上限を上げます。

sf <command> ... --max-credits <higherLimit> --json

credit_balance_insufficient

credit_balance_insufficient は、上限は足りていても account の利用可能 クレジットが足りない時に返ります。

sf credits balance --json

見る key:

• balance.available_credits
• balance.remaining_credits
• balance.reserved_credits
• balance.consumption_order
• balance.grants[].source_type
• balance.grants[].available_credits
• balance.grants[].expires_at

残高が足りない場合は、Free / Pro / Credit Pack / campaign 付与のどれが不足しているかを確認します。 クレジットが追加された後、同じ条件で再実行します。

Credit Pack で復旧できるのは credit_balance_insufficient です。daily_*_quota_exceeded / monthly_*_quota_exceeded は plan quota の問題なので、追加 credit ではなく usage の reset、条件の絞り込み、または plan / contract 側の見直しが必要です。

再発防止

• deep signal / bulk 前に usage estimate を読む
• estimate 以下の --max-credits で実行しない
• sf credits balance --json で available_credits を確認してから長い ワークフロー を始める
• gaps[] の条件を、0 件扱いで完了にしない

クレジットは、request と深い signal / bulk の実行時に発生します。無料枠は広めに使えますが、根こそぎ取得にならないよう残高と上限を見ます。