クレジットと maxCredits の失敗

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

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

まず見るコマンド

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 は、上限指定つきの課金実行で、実行上限を明示していないときに返ります。CLI に上限を指定するフラグは現在ありません。この error が返ったら実行を止め、返ってきた error.hint と error.suggested_next_commands に従ってください。

sf <command> --help --json
sf credits balance --json

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

max_credits_exceeded

max_credits_exceeded は、実行に必要なクレジットが指定された上限を超えたときに返ります。 この場合、クレジットは消費されません。

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

sf search "東証プライムの上場企業で生成AIに関連" --json
sf signals <companyId> --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 側を見直してください。

再発防止

• credit-consuming Signal read の前に usage estimate を読む
• usage estimate を確認せずに課金実行へ進まない
• sf credits balance --json で available_credits を確認してから長いワークフローを始める
• gaps[] の条件を、0 件扱いで完了にしない

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