Skip to main content
Ausgabenlimits begrenzen, wie viel jeder Entwickler über Ihr Claude-Apps-Gateway an einem bestimmten Tag, einer Woche oder einem Monat ausgeben kann. Wenn ein Entwickler sein Limit überschreitet, gibt das Gateway 429 bei seiner nächsten Anfrage zurück und blockiert ihn, bis sich der Zeitraum zurückgesetzt hat oder ein Administrator das Limit erhöht. Verwenden Sie Ausgabenlimits, um jedem Entwickler, einer Gruppe oder der gesamten Organisation eine Obergrenze für eine gemeinsam genutzte Anmeldedaten zu setzen. Ein Claude-Apps-Gateway leitet alle Inferenzen über eine gemeinsame Upstream-Anmeldedaten weiter, sodass die Rechnung Ihres Anbieters alles dieser Anmeldedaten zuordnet, nicht einzelnen Entwicklern. Ohne Pro-Entwickler-Limits kann eine unkontrollierte Agent-Flotte die gesamte Verpflichtung der Organisation ausgeben. Ausgabenlimits sind die Pro-Entwickler-Ansicht des Gateways und ein Schutzschalter auf dieser gemeinsamen Rechnung.

​
Limit festlegen

Mit dem konfigurierten admin:-Block in gateway.yaml stellt das Gateway eine Admin-API unter /v1/organizations/spend_limits bereit und erzwingt Limits live bei jeder Inferenzanfrage. Limits selbst werden über diese API festgelegt, nicht in gateway.yaml; jede POST /v1/organizations/spend_limits-Anfrage erstellt oder ersetzt ein Limit aus {scope, amount, period}. Die API spiegelt die Drahtformate der öffentlichen Admin-API von Anthropic für Ausgabenlimits wider, sodass ein HTTP-Client, der gegen diesen Vertrag geschrieben wurde, das Gateway ansteuern kann, indem er seine Basis-URL ändert. Diese Anfrage legt einen organisationsweiten Standard von 500 USD pro Monat für jeden Entwickler fest:
Diese Anfrage legt ein strengeres Limit von 100 USD pro Tag für jedes Mitglied der Gruppe contractors fest:
Ein Gruppen- oder Organisationslimit ist ein Pro-Sitz-Standard, den jedes Mitglied erbt, nicht ein gemeinsamer Pool. Pro Zeitraum wird das effektive Limit eines Entwicklers in dieser Reihenfolge aufgelöst: ein Pro-Benutzer-Override, dann das restriktivste seiner Gruppenlimits, dann der Organisationsstandard, dann unbegrenzt. admin.group_limit_mode: max dreht das Multi-Gruppen-Tie-Break zu am wenigsten restriktiv um.

​
Authentifizierung bei der Admin-API

Senden Sie eines der folgenden:
  • Ein x-api-key-Header, der einem Schlüssel in admin.write_keys für vollständigen Zugriff oder admin.read_keys für GET-only-Zugriff entspricht. Jeder Schlüssel trägt eine id, die im Audit-Log als admin-key:<id> angezeigt wird, also geben Sie Terraform, CI und jeder Automatisierung seinen eigenen.
  • Ein Gateway-Bearer-Token, dessen groups-Anspruch eines der admin.admin_groups enthält. Dies ist vollständiger Zugriff und wird als oidc:<sub> überwacht, also bevorzugen Sie es für menschliche Administratoren.

​
Wie die Durchsetzung funktioniert

Bei jeder /v1/messages-Anfrage schlägt das Gateway die Limits und die bisherigen Ausgaben des Entwicklers in einer Postgres-Abfrage nach. Ein Entwickler, der ein Limit überschreitet, erhält eine 429 mit error.type: billing_error und dem Header x-should-retry: false. Die Nachricht nennt den Zeitraum und die Rücksetzeit, z. B. spend limit reached (daily; resets 2026-08-08 00:00 UTC), gefolgt von Ihrer admin.blocked_message, falls gesetzt. Wenn ein Entwickler mehrere Limits gleichzeitig überschreitet, nennt die Nachricht das Limit, das zuletzt zurückgesetzt wird. Die Antwort enthält auch einen retry-after-Header mit den Sekunden bis zu diesem Zurücksetzen. Vor v2.1.225 auf dem Gateway-Server war die Nachricht spend limit reached ohne Zeitraum, Rücksetzeit oder retry-after-Header. Ab v2.1.227 listet die Protokollreferenz unter <public_url>/protocol auch die genauen Antwortheader für Nutzungslimits und den 429-Body auf. Limits werden an UTC-Kalendergrenzen zurückgesetzt: täglich um 00:00 UTC, wöchentlich am Montag und monatlich am ersten. Das Gateway blockiert /v1/messages/count_tokens nie, da Token-Zählung kostenlos ist.

​
Wie Anfragen bepreist werden

Nach jeder Antwort liest ein Nutzungszähler die Token-Anzahlen und addiert die Kosten zu den täglichen, wöchentlichen und monatlichen Zählern. Er berührt nie die an den Client gesendeten Bytes, daher kann ein Messfehler eine Antwort nicht unterbrechen. Die Beträge sind USD-Schätzungen, ein Schutzschalter statt einer Rechnung; für die Abrechnung gleichen Sie gegen die Nutzungsberichte Ihres Anbieters ab. Der Zähler wählt die Sätze jeder Anfrage in dieser Reihenfolge:
  1. Eine passende pricing.overrides-Zeile für den Upstream, der die Anfrage bedient hat. Erfordert v2.1.227 oder später.
  2. Listenpreis für die Upstream-Modell-ID, die Zeichenkette, die das Gateway an den Anbieter sendet, wenn die Claude Code-Kostentabelle sie erkennt. Die Tabelle akzeptiert Anthropic-, Amazon Bedrock-, Google Cloud Agent Platform- und Microsoft Foundry-ID-Formate.
  3. Listenpreis für die models[].id, die Sie dieser Upstream-ID zugeordnet haben, für Upstream-Zeichenketten, die keinen Modellnamen enthalten, z. B. ein Amazon Bedrock-Application-Inference-Profile-ARN oder einen Microsoft Foundry-Bereitstellungsnamen. Erfordert v2.1.218 oder später.
  4. Die Stufe für unbekannte Modelle von $5/$25 pro Million Input-/Output-Token, sodass eine ID, die der Zähler nicht einordnen kann, nie kostenlos ist. Das Gateway warnt beim Start und einmal pro ID zur Laufzeit, wenn es diese Stufe verwendet.
Welcher Satz auch gilt, der Zähler multipliziert den Betrag dann mit pricing.multiplier, Standard 1. Client-Abbrüche werden ebenfalls berechnet. Wenn ein Stream ohne den finalen Nutzungsrahmen des Upstream endet, berechnet der Zähler eine Untergrenze von etwa vier Zeichen pro Output-Token für den bereits an den Client gesendeten Text, sodass das vorzeitige Abbrechen von Anfragen ein Limit nicht umgeht.

​
Postgres-Verfügbarkeit

Die Vorabprüfung fragt Postgres mit einem Zwei-Sekunden-Timeout ab. Wenn der Speicher nicht erreichbar ist oder das Timeout überschreitet, schlägt die Durchsetzung standardmäßig offen fehl: Die Anfrage wird fortgesetzt, das Gateway protokolliert eine Warnung, und die Antwort enthält keine anthropic-ratelimit-unified-*-Header. Setzen Sie enforcement.fail_closed_on_error: true, um stattdessen geschlossen fehlzuschlagen, was denselben 429 billing_error zurückgibt, aber mit der Nachricht spend limit unavailable und ohne Zeitraum, Rücksetzeit oder retry-after-Header. Offen-Fehler verhindert, dass ein Speicherausfall zu einem Inferenz-Ausfall wird; geschlossen-Fehler garantiert keine ungemessenen Ausgaben. Offen-Fehler hilft nur, während Ihr Load Balancer oder Orchestrator noch Traffic zum Gateway leitet. Siehe Outage behavior für store.readiness_grace_seconds, das Replikas durch einen kurzen Ausfall hindurch ihren Readiness-Check bestehen lässt.

​
Nutzungswarnungen in Claude Code

Claude Code warnt einen Entwickler, wenn er sich seinem Limit nähert: sobald die Auslastung 75 % überschreitet, und erneut über 95 % seines am meisten verbrauchten Limits. Wenn das Gateway eine Anfrage blockiert, zeigt Claude Code die 429-Nachricht des Gateways wie sie ist, einschließlich Ihrer admin.blocked_message. Die Warnung funktioniert über Antwortheader:
  • Mit v2.1.225 oder später auf dem Gateway-Server trägt jede erfolgreiche /v1/messages-Antwort für einen Entwickler, der ein Limit hat, seine eigene Limit-Auslastung und Rücksetzeit in den anthropic-ratelimit-unified-*-Headern.
  • Mit v2.1.225 oder später auch auf der Maschine des Entwicklers liest Claude Code die Header und zeigt die Warnung.
Die Header beschreiben immer das eigene Limit des Entwicklers: Das Gateway entfernt die Rate-Limit-Header des Upstream-Anbieters, die Ihre gemeinsame Quote beschreiben, und leitet sie nie weiter. Mit v2.1.251 oder später auf der Maschine des Entwicklers liest Claude Code auch dieselben Header, um eine Spend limit-Leiste in /usage anzuzeigen, mit dem Prozentsatz ihres verwendeten Limits und wann es zurückgesetzt wird, und um ein rate_limits.spend_limit-Objekt zur Statuszeile-Eingabe hinzuzufügen. Claude Code zeigt beide als Prozentsatz statt als Dollarbetrag an und benötigt nichts Neueres als v2.1.225 auf dem Gateway-Server.

​
Admin-API-Referenz

Die folgenden Endpunkte werden unter /v1/organizations/spend_limits bereitgestellt. Konventionen spiegeln Anthropics Admin-API wider:
  • Ein type auf jedem Objekt
  • spl_-präfixierte IDs
  • Beträge als Ganzzahl-Strings von USD-Cent; POST lehnt jede andere currency mit 400 ab
  • Die {type: "error", error: {type, message}, request_id}-Fehler-Umhüllung
  • Ein request-id-Response-Header auf jeder Admin-Antwort, Erfolg oder Fehler; Fehlertexte enthalten ihn auch als request_id
Jede Mutation schreibt eine Vor-/Nach-Zeile in admin_audit in der gleichen Transaktion, zugeordnet zu admin-key:<id> oder oidc:<sub>. Das Gateway stellt die Spend-Limits-Endpunkte nur bereit. Andere Admin-API-Oberflächen, wie die spend_limit_increase_requests-Warteschlange, sind nicht Teil der Admin-API des Gateways.

​
/effective

GET /v1/organizations/spend_limits/effective gibt Anthropics SpendSummary-Schema zurück: jede Zeile ist ein Principal für einen Zeitraum, mit dem aufgelösten Limit, den Ausgaben bis zum aktuellen Zeitraum und einem actor-Objekt. Gateway-spezifische Unterschiede:
  • user_id ist die OIDC sub.
  • actor.name und actor.email_address sind null, bis die erste Inferenzanfrage des Principal durch das Gateway erfolgt. Das Gateway hat kein Benutzerverzeichnis; es zeichnet zuletzt gesehene Werte aus dem Session-JWT jedes Benutzers auf.
  • Jede Zeile trägt auch ein groups-Array, die zuletzt gesehenen IdP-Gruppen des Principal. Dies ist eine Gateway-Erweiterung, damit eine Admin-UI jeden anwendbaren Limit-Tier anzeigen kann; Anthropic-förmige Clients ignorieren es.
  • Ohne einen user_ids[]-Filter listet es Principal mit aufgezeichneten Ausgaben auf, da das Gateway nicht alle Organisationsmitglieder aufzählen kann.
Gruppen-basierte Limits werden gegen diese zuletzt gesehenen Gruppen mit dem gleichen group_limit_mode-Tie-Break aufgelöst, den die Durchsetzung verwendet, sodass der Viewer das tatsächlich anwendbare Limit anzeigt.
q= und user_ids[]= fahren GET-Abfrage-Strings, daher erfasst jeder Fronting-Proxy oder Load-Balancer sie in seinen Zugriffslogs. Wenn Ihre PII-Log-Richtlinie streng ist, bereinigen Sie diese Parameter dort.

​
/audit

Gibt den Ausgabenlimit-Mutationsverlauf zurück: wer welches Limit geändert hat, mit Vor-/Nach-Snapshots, neueste zuerst. has_more ist exakt. Dieser Endpunkt folgt den lokalen Admin-API-Konventionen statt einer First-Party-Drahtform.

​
Pagination

Die rohe Liste paginiert nach after_id und before_id, die sich gegenseitig ausschließende spl_…-IDs sind; Ergebnisse werden nach Erstellung sortiert und has_more spiegelt die Traversierungsrichtung wider. /effective paginiert nach dem undurchsichtigen next_page-Token, der als ?page= zurückgegeben wird, mit Principal in aufsteigender Reihenfolge sortiert, sodass Seiten stabil bleiben, während Ausgaben aufgezeichnet werden. limit ist 1–1000, Standard 20, auf beiden. /audit paginiert nach after_id, der numerischen id des letzten Ereignisses auf der vorherigen Seite, und sein limit hat einen Standard von 100.

​
Datenzyklus

Das Gateway enthält vier ausgabenbezogene Tabellen; ein stündlicher Sweep erzwingt die Aufbewahrungsfenster: Wenn ein Entwickler geht, löschen Sie alle Pro-Benutzer-Limits über DELETE /v1/organizations/spend_limits/{id}; ihre Ausgaben und Identitätszeilen veralten auf den oben genannten Aufbewahrungsfenstern. Um eine Person sofort zu löschen, für Offboarding oder eine Datenschutzanfrage (DSAR), führen Sie DELETE FROM principal_emails WHERE principal = '<sub>' direkt gegen die Gateway-Datenbank aus. Das entfernt die einzige Tabelle, die ihre E-Mail, ihren Namen und ihre Gruppen enthält. Die spend- und admin_audit-Zeilen verweisen nur auf die pseudonyme OIDC sub und veralten auf ihren eigenen Fenstern.