429 à sa prochaine requête et le bloque jusqu’à ce que la période se réinitialise ou qu’un administrateur augmente la limite. Utilisez les limites de dépenses pour donner à chaque développeur, groupe ou l’ensemble de l’organisation un plafond sur une credential que tout le monde partage.
Une passerelle Claude apps transfère toutes les inférences via une credential amont partagée, de sorte que la facture de votre fournisseur attribue tout à cette credential, et non aux développeurs individuels. Sans limites par développeur, une flotte d’agents incontrôlée peut dépenser l’engagement entier de l’organisation. Les limites de dépenses constituent la vue par développeur de la passerelle et le disjoncteur sur cette facture partagée.
Définir une limite
Avec le blocadmin: configuré dans gateway.yaml, la passerelle sert une API admin à /v1/organizations/spend_limits et applique les limites en direct à chaque requête d’inférence. Les limites elles-mêmes sont définies via cette API, pas dans gateway.yaml ; chaque requête POST /v1/organizations/spend_limits crée ou remplace une limite à partir de {scope, amount, period}. L’API reflète les formes de câblage des points de terminaison de limites de dépenses de l’API Admin public d’Anthropic, de sorte qu’un client HTTP écrit selon ce contrat peut cibler la passerelle en changeant son URL de base.
Cette requête définit une limite par défaut à l’échelle de l’organisation de 500 $ par mois pour chaque développeur :
contractors :
Une limite de groupe ou d’organisation est une limite par siège par défaut que chaque membre hérite, pas un pool partagé. Par période, la limite effective d’un développeur se résout dans cet ordre : un remplacement par utilisateur, puis la plus restrictive de ses limites de groupe, puis la limite par défaut de l’organisation, puis illimitée.
admin.group_limit_mode: max bascule le départage multi-groupe vers la moins restrictive à la place.
S’authentifier auprès de l’API admin
Envoyez l’un des éléments suivants :- Un en-tête
x-api-keycorrespondant à une clé dansadmin.write_keyspour un accès complet, ouadmin.read_keyspour un accès en lecture seule avecGET. Chaque clé porte unidqui apparaît dans le journal d’audit commeadmin-key:<id>, donc donnez à Terraform, CI et à chaque automatisation la sienne. - Un jeton bearer de passerelle dont la revendication
groupsinclut l’un desadmin.admin_groups. C’est un accès complet et s’audite commeoidc:<sub>, donc préférez-le pour les administrateurs humains.
Comment l’application fonctionne
À chaque requête/v1/messages, la passerelle résout les limites du développeur et les dépenses à ce jour de la période en une seule requête Postgres. S’il dépasse une limite, la requête retourne 429 avec error.type: billing_error et l’en-tête x-should-retry: false.
Le message nomme la période et l’heure de réinitialisation, par exemple spend limit reached (daily; resets 2026-08-08 00:00 UTC), suivi de votre admin.blocked_message s’il est défini. Quand un développeur dépasse plusieurs limites à la fois, le message nomme la limite qui se réinitialise en dernier. La réponse porte également un en-tête retry-after avec les secondes restantes jusqu’à cette réinitialisation. Avant v2.1.225 sur le serveur de la passerelle, le message était spend limit reached sans période, heure de réinitialisation, ou en-tête retry-after.
Sur v2.1.227 ou ultérieur, la référence de protocole à <public_url>/protocol liste également les en-têtes de réponse de limite d’utilisation exacts et le corps 429.
Les limites se réinitialisent sur les limites du calendrier UTC : quotidiennement à 00:00 UTC, hebdomadairement le lundi, et mensuellement le premier. La passerelle ne bloque jamais /v1/messages/count_tokens, car le comptage de tokens est gratuit.
Comment les requêtes sont tarifées
Après chaque réponse, un compteur d’utilisation lit les nombres de tokens et ajoute le coût aux compteurs quotidiens, hebdomadaires et mensuels. Il ne touche jamais aux octets envoyés au client, de sorte qu’une défaillance de mesure ne peut pas casser une réponse. Les montants sont des estimations en USD, un disjoncteur plutôt qu’une facture ; pour la facturation, rapprochez-vous de la déclaration d’utilisation de votre fournisseur. Le compteur choisit les tarifs de chaque requête dans cet ordre :- Une ligne
pricing.overridescorrespondante pour l’amont qui a servi la requête. Nécessite v2.1.227 ou ultérieur. - Tarif de liste pour l’ID de modèle amont, la chaîne que la passerelle envoie au fournisseur, quand la table de coûts Claude Code la reconnaît. La table accepte les formes Anthropic, Amazon Bedrock, Google Cloud’s Agent Platform, et Microsoft Foundry ID.
- Tarif de liste pour le
models[].idque vous avez mappé à cet ID amont, pour les chaînes amont qui ne portent pas de nom de modèle, comme un ARN de profil d’inférence d’application Amazon Bedrock ou un nom de déploiement Microsoft Foundry. Nécessite v2.1.218 ou ultérieur. - Le tier de modèle inconnu de 5 par million de tokens d’entrée/sortie, de sorte qu’un ID que le compteur ne peut pas placer n’est jamais gratuit. La passerelle avertit au démarrage et une fois par ID à l’exécution quand elle utilise ce tier.
pricing.multiplier, par défaut 1.
Les abandons de clients sont également facturés. Quand un flux se termine sans la trame d’utilisation finale de l’amont, le compteur facture une estimation de plancher d’environ quatre caractères par token de sortie pour le texte déjà envoyé au client, de sorte que l’abandon de requêtes tôt ne contourne pas une limite.
Disponibilité de Postgres
La pré-vérification interroge Postgres avec un délai d’expiration de deux secondes. Si le magasin est inaccessible ou expire, l’application échoue ouvertement par défaut : la requête procède, la passerelle enregistre un avertissement, et la réponse ne porte pas d’en-têtesanthropic-ratelimit-unified-*. Définissez enforcement.fail_closed_on_error: true pour échouer fermé à la place, ce qui retourne le même 429 billing_error mais avec le message spend limit unavailable et sans période, heure de réinitialisation, ou en-tête retry-after. L’échec ouvert empêche une panne de magasin de devenir une panne d’inférence ; l’échec fermé garantit aucune dépense non mesurée.
L’échec ouvert n’aide que si votre équilibreur de charge ou orchestrateur achemine toujours le trafic vers la passerelle. Voir Comportement en cas de panne pour store.readiness_grace_seconds, qui maintient les répliques passant leur vérification de disponibilité à travers une courte panne.
Avertissements d’utilisation dans Claude Code
Claude Code avertit un développeur à l’approche de sa limite : une fois que l’utilisation dépasse 75 %, et à nouveau au-delà de 95 % de sa limite la plus consommée. Quand la passerelle bloque une requête, Claude Code affiche le message429 de la passerelle tel quel, y compris votre admin.blocked_message.
L’avertissement fonctionne à partir des en-têtes de réponse :
- Avec v2.1.225 ou ultérieur sur le serveur de la passerelle, chaque réponse
/v1/messagesréussie pour un développeur qui a une limite porte son propre taux d’utilisation de limite et l’heure de réinitialisation dans les en-têtesanthropic-ratelimit-unified-*. - Avec v2.1.225 ou ultérieur sur la machine du développeur également, Claude Code lit les en-têtes et affiche l’avertissement.
/usage, avec le pourcentage de leur limite utilisée et quand elle se réinitialise, et pour ajouter un objet rate_limits.spend_limit à la ligne de statut d’entrée. Claude Code affiche les deux en tant que pourcentage plutôt qu’un montant en dollars, et n’a besoin de rien de plus récent que v2.1.225 sur le serveur de la passerelle.
Référence de l’API Admin
Les points de terminaison ci-dessous sont servis sous/v1/organizations/spend_limits.
Les conventions reflètent l’API Admin d’Anthropic :
- Un
typesur chaque objet - IDs préfixés
spl_ - Montants sous forme de chaînes de nombre entier de cents USD ;
POSTrejette toute autrecurrencyavec400 - L’enveloppe d’erreur
{type: "error", error: {type, message}, request_id} - Un en-tête de réponse
request-idsur chaque réponse admin, succès ou erreur ; les corps d’erreur le portent également en tant querequest_id
admin_audit dans la même transaction, attribuée à admin-key:<id> ou oidc:<sub>.
La passerelle sert les points de terminaison des limites de dépenses uniquement. Les autres surfaces de l’API Admin, telles que la file d’attente spend_limit_increase_requests, ne font pas partie de l’API admin de la passerelle.
/effective
GET /v1/organizations/spend_limits/effective retourne le schéma SpendSummary d’Anthropic : chaque ligne est un principal pour une période, avec la limite résolue, les dépenses à ce jour de la période et un objet actor. Différences spécifiques à la passerelle :
user_idest l’OIDCsub.actor.nameetactor.email_addresssontnulljusqu’à la première requête d’inférence du principal via la passerelle. La passerelle n’a pas de répertoire utilisateur ; elle enregistre les valeurs dernièrement vues à partir du JWT de session de chaque utilisateur.- Chaque ligne porte également un tableau
groups, les groupes IdP dernièrement vus du principal. C’est une extension de passerelle pour qu’une interface utilisateur admin puisse afficher chaque niveau de limite qui s’applique ; les clients façonnés par Anthropic l’ignorent. - Sans un filtre
user_ids[], il liste les principaux avec des dépenses enregistrées, car la passerelle ne peut pas énumérer tous les membres de l’organisation.
group_limit_mode que l’application utilise, de sorte que la visionneuse affiche la limite qui s’applique réellement.
/audit
Retourne la piste de mutation de limite de dépenses : qui a changé quelle limite, avec les snapshots avant/après, plus récente en premier. has_more est exact. Ce point de terminaison suit les conventions de l’API Admin locale plutôt qu’une forme de câblage de première partie.
Pagination
La liste brute pagine parafter_id et before_id, qui sont des IDs spl_… mutuellement exclusifs ; les résultats sont ordonnés par création et has_more reflète la direction de traversée. /effective pagine par le jeton opaque next_page repassé comme ?page=, avec les principaux ordonnés en ordre croissant de sorte que les pages restent stables pendant que les dépenses sont enregistrées. limit est 1–1000, par défaut 20, sur les deux. /audit pagine par after_id, l’ID numérique id du dernier événement sur la page précédente, et sa limit par défaut est 100.
Cycle de vie des données
La passerelle contient quatre tables liées aux dépenses ; un balayage horaire applique les fenêtres de rétention :
Lorsqu’un développeur part, supprimez toute limite par utilisateur via
DELETE /v1/organizations/spend_limits/{id} ; ses lignes de dépenses et d’identité vieillissent sur les fenêtres de rétention ci-dessus. Pour effacer une personne immédiatement, pour l’offboarding ou une demande d’accès aux données (DSAR), exécutez DELETE FROM principal_emails WHERE principal = '<sub>' directement contre la base de données de la passerelle. Cela supprime la seule table contenant leur email, nom et groupes. Les lignes spend et admin_audit font référence uniquement au pseudonyme OIDC sub et vieillissent sur leurs propres fenêtres.
Connexes
- Configuration
adminetenforcement: activation de l’API admin et ajustement de la rétention - Guide de déploiement : schéma Postgres et conseils de sauvegarde