結論：上限はuser単位で重ね、請求と分けて監視する
先に答えると、Claude apps gatewayのspend limitsでは、user、RBAC group、organizationごとにdaily、weekly、monthlyのcapを設定し、開発者がどれか一つでも超えると次のinference requestを429で止めます。組織全体が一つのupstream credentialを共有しても、OIDCのuser別に制御できます。ただし計測はtoken countと公開list priceによる推定であり、providerの請求書そのものを固定する機能ではありません。
読者の具体的な困りごとは、共有credentialの請求ではrunaway agentや特定developerの支出を止められず、誰の利用が上限へ達したか説明しにくいことです。読了後は、organization default、group、user overrideと三期間を組み合わせ、fail-openまたはfail-closedを選べます。次の行動は、通常利用者、contractor、高負荷担当の三personaへ日・週・月の許容額を書くことです。
Claude apps gatewayとspend limitsの前提
Claude apps gatewayはClaude appsを各cloud providerへつなぐself-hosted gatewayです。OIDC SSO、group別model access、policy、telemetryを集約し、upstream credentialをdeveloperへ配りません。spend limitsは認証済みprincipalの支出をPostgresへ記録し、request前に上限を判定します。
capはgateway.yamlではなくAdmin APIで作成します。scope.typeはuser、rbac_group、organization、amountはUSD centの整数文字列、periodはdaily、weekly、monthlyです。nullはunlimited、文字列の0は全requestをblockします。
groupまたはorganization capは共有poolではなく、各developerが継承するper-seat defaultです。effective capはuser override、最も厳しいgroup cap、organization default、unlimitedの順で解決されます。
日次・週次・月次をどう使い分けるか
dailyはloopや大量parallel sessionを当日中に止める運用上限です。開発者が通常一日に行うreview、実装、調査の上位値へ余裕を足し、異常を翌日まで持ち越さない額にします。weeklyは曜日差とsprint作業を吸収しつつ、毎日上限ぎりぎりを使う状態を検出します。monthlyは契約commitmentや部署予算に近い統制ですが、per-seat defaultなので「部署100万円の共有枠」と読み替えてはいけません。
三期間は独立して効き、どれか一つを超えればblockされます。resetはUTC calendar boundaryで、dailyは00:00 UTC、weeklyは月曜00:00 UTC、monthlyは月初00:00 UTCです。日本時間の業務日とずれるため、日次reportはUTC periodとJST稼働日の両方を表示します。Claude Code v2.1.225以降はgatewayのspend-limit warningにcap、reset時刻、operator messageが示されるため、利用者が単なる通信障害と区別しやすくなりました。
amountは「低ければ安全」ではありません。上限到達で重要なrelease作業まで一律停止すると、別credentialへの迂回を誘発します。通常作業のbaseline、異常例、一requestの最大規模、緊急時の増額ownerを決めます。contractor groupには短いdaily cap、通常employeeにはweeklyとmonthly、build担当などの高負荷userには期限付きoverrideを重ねると説明しやすくなります。
429停止と計測の読み方
gatewayは各/v1/messages request前にeffective capとperiod-to-date spendをPostgresで確認します。超過時は429、billing_error、x-should-retry falseを返します。自動retryを止め、period reset、cap変更、task終了のどれかを人が選びます。無料のcount_tokensはcap超過中も使えます。
response後はusage tokenをlist priceで評価し三期間へ加算します。abortで最終usageが届かなくてもstream量から保守的に推定し、未知modelもdefault tierで計測します。custom aliasはmodel mappingとversionを確認します。
この値はcircuit breaker用のestimateです。discountやprovider固有料金は請求と一致しないため、Anthropic Admin APIや各cloudのauthoritative reportと日次でreconcileします。
費用上限を設計する7手順
- upstream credential、OIDC principal、group claim、provider billingのdata flowを図にします。
- 通常、contractor、高負荷のpersonaごとに一日、一週、一月のbaselineを集計します。
- organizationのmonthly default、groupのdailyまたはweekly、user overrideの順でcap案を作ります。
- amountをUSD cent文字列にし、admin APIのwrite keyをautomationごとに分離して登録します。
- /effectiveでprincipal、period、to-date spend、適用scopeを確認し、想定した優先順位か試験します。
- 小さなtest capで429、x-should-retry false、blocked message、UTC reset、増額再開を確認します。
- audit trailとprovider請求を照合し、例外overrideの期限と承認者を月次reviewします。
human操作はOIDC admin group、TerraformやCIは個別ID付きwrite keyを使い、mutation auditへactorを残します。read-only keyも分けます。
fail-openかfail-closedかを決める
pre-checkのPostgres queryは二秒timeoutで、store障害時は既定でfail open、つまりrequestを通しwarningを残します。可用性を優先できますが、unmetered spendが発生します。enforcement.fail_closed_on_errorをtrueにすると同じ429 billing_errorでspend limit unavailableを返し、未計測支出を防げます。開発sandboxはfail open、規制業務や厳格予算はfail closedのように、業務影響と予算riskを比較します。
チェックリストは、user識別がOIDC subで安定しているか／group claimを検証したか／capが共有poolでないと説明したか／三期間のUTC resetを記録したか／429をretryしないか／unknown model warningを監視するか／Postgres障害時のmodeを決めたか／admin keyを分離したか／mutation auditを保存するか／provider請求とreconcileするか、です。
cap到達後に自動で増額できますか？
Admin APIで変更できますが、無条件自動増額はcircuit breakerを無効にします。残作業、追加額、期限、承認者を確認します。
session単位の予算と同じですか？
異なります。gateway spend limitsはdeveloperの期間累計、Managed Agents Session budgetsは一sessionのlist costを止めます。
費用計測が失敗したらrequestも失敗しますか？
既定はfail openです。費用統制を優先する場合だけ、影響を試験してfail closedへ変更します。
scope、period、429、計測、Admin APIはAnthropic公式Gateway spend limits、gatewayの提供基盤と構成は公式Claude apps gateway、費用全体の考え方は公式Manage costsで確認できます。
一般的な費用分解はClaude Codeのコスト管理、一sessionの上限はManaged Agents Session budgets、変更証跡は監査ログ設計を参照してください。Miraigentの無料診断では、persona別cap、例外、429対応、請求照合を一つの運用表へ整理します。