SpyBara
Go Premium

claude-apps-gateway-spend-limits.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 53 additions and 27 deletions.

2026
Wed 9 22:58

Limiti di spesa del gateway delle app Claude

Limita la spesa di ogni sviluppatore attraverso il gateway delle app Claude per giorno, settimana o mese. Imposta i limiti con un'API Admin e il gateway li applica in tempo reale su ogni richiesta.

I limiti di spesa limitano quanto ogni sviluppatore può spendere attraverso il tuo gateway delle app Claude in un determinato giorno, settimana o mese. Quando uno sviluppatore supera il suo limite, il gateway restituisce 429 alla sua prossima richiesta e lo blocca fino al ripristino del periodo o fino a quando un amministratore non aumenta il limite. Utilizza i limiti di spesa per dare a ogni sviluppatore, gruppo o all'intera organizzazione un tetto massimo su una credenziale che tutti condividono.

Un gateway delle app Claude inoltra tutta l'inferenza attraverso una credenziale upstream condivisa, quindi la fattura del tuo provider attribuisce tutto a quella credenziale, non ai singoli sviluppatori. Senza limiti per sviluppatore, una flotta di agenti incontrollata può spendere l'intero impegno dell'organizzazione. I limiti di spesa sono la vista per sviluppatore del gateway e il circuito di protezione su quella fattura condivisa.

Imposta un limite

Con il blocco admin: configurato in gateway.yaml, il gateway serve un Admin API su /v1/organizations/spend_limits e applica i limiti in tempo reale su ogni richiesta di inferenza. I limiti stessi vengono impostati attraverso quell'API, non in gateway.yaml; ogni richiesta POST /v1/organizations/spend_limits crea o sostituisce un limite da {scope, amount, period}. L'API rispecchia le forme dei dati degli endpoint dei limiti di spesa dell'Admin API pubblico di Anthropic, quindi un client HTTP scritto per quel contratto può indirizzarsi al gateway modificando il suo URL di base.

Questa richiesta imposta un valore predefinito a livello di organizzazione di $500 al mese per ogni sviluppatore:

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}'

Questa richiesta aggiunge un limite più restrittivo di $100 al giorno per ogni membro del gruppo contractors:

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "rbac_group", "rbac_group_id": "contractors"}, "amount": "10000", "period": "daily"}'
Campo Valori Descrizione
scope.type user, rbac_group, organization user indirizza uno sviluppatore tramite il suo OpenID Connect (OIDC) sub, l'ID utente stabile assegnato dal tuo provider di identità; passalo come scope.user_id. rbac_group indirizza un gruppo IdP per nome; passalo come scope.rbac_group_id. organization è il valore predefinito a livello di organizzazione. Il gateway accetta tutti e tre; l'POST pubblico di Anthropic è solo per utenti oggi.
amount Stringa di numero intero di centesimi USD, o null null è illimitato. "0" è un limite zero, che blocca ogni richiesta.
period daily, weekly, monthly Un ambito può contenere un limite per periodo, e ognuno si applica indipendentemente: uno sviluppatore è bloccato se supera uno qualsiasi di essi.

Un limite di gruppo o organizzazione è un valore predefinito per posto che ogni membro eredita, non un pool condiviso. Per periodo, il limite effettivo di uno sviluppatore si risolve in questo ordine: un override per utente, quindi il più restrittivo dei suoi limiti di gruppo, quindi il valore predefinito dell'organizzazione, quindi illimitato. admin.group_limit_mode: max capovolge il tie-break multi-gruppo al meno restrittivo invece.

Autentica all'Admin API

Invia uno dei seguenti:

  • Un header x-api-key che corrisponde a una chiave in admin.write_keys per accesso completo, o admin.read_keys per accesso di sola lettura con GET. Ogni chiave porta un id che appare nel registro di audit come admin-key:<id>, quindi assegna a Terraform, CI e a ogni automazione la propria.
  • Un token bearer del gateway il cui claim groups include uno dei admin.admin_groups. Questo è accesso completo e viene registrato come oidc:<sub>, quindi preferiscilo per gli amministratori umani.

Come funziona l'applicazione

Su ogni richiesta /v1/messages, il gateway risolve i limiti dello sviluppatore e la spesa da inizio periodo in una query Postgres. Se superano uno qualsiasi dei limiti, la richiesta restituisce 429 con error.type: billing_error e l'header x-should-retry: false.

Il messaggio nomina il periodo e l'ora di reset, come spend limit reached (daily; resets 2026-08-08 00:00 UTC), seguito dal tuo admin.blocked_message se impostato. Quando uno sviluppatore supera diversi limiti contemporaneamente, il messaggio nomina il limite che si ripristina per ultimo. La risposta contiene anche un header retry-after con i secondi rimanenti fino a quel reset. Prima della versione v2.1.225 sul server gateway, il messaggio era spend limit reached senza periodo, ora di reset o header retry-after.

Su v2.1.227 o successivo, il riferimento del protocollo in <public_url>/protocol elenca anche gli header di risposta esatti per il limite di utilizzo e il corpo 429.

I limiti si ripristinano sui confini del calendario UTC: giornalmente alle 00:00 UTC, settimanalmente il lunedì e mensilmente il primo. Il gateway non blocca mai /v1/messages/count_tokens, perché il conteggio dei token è gratuito.

Come vengono prezzate le richieste

Dopo ogni risposta, un misuratore di utilizzo legge i conteggi dei token e aggiunge il costo ai contatori giornalieri, settimanali e mensili. Non tocca mai i byte inviati al client, quindi un errore di misurazione non può interrompere una risposta. Gli importi sono stime in USD, un circuito di protezione piuttosto che una fattura; per la fatturazione, riconcilia con il rapporto di utilizzo del tuo provider.

Il misuratore sceglie i tassi di ogni richiesta in questo ordine:

  1. Una riga pricing.overrides corrispondente per l'upstream che ha servito la richiesta. Richiede v2.1.227 o successivo.
  2. Prezzo di listino per l'ID del modello upstream, la stringa che il gateway invia al provider, quando la tabella dei costi di Claude Code la riconosce. La tabella accetta forme di Anthropic, Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry ID.
  3. Prezzo di listino per il models[].id che hai mappato a quell'ID upstream, per stringhe upstream che non contengono un nome di modello, come un ARN del profilo di inferenza di Amazon Bedrock o un nome di distribuzione di Microsoft Foundry. Richiede v2.1.218 o successivo.
  4. Il livello di modello sconosciuto di $5/$25 per milione di token di input/output, quindi un ID che il misuratore non riesce a posizionare non è mai gratuito. Il gateway avvisa all'avvio e una volta per ID al runtime quando utilizza questo livello.

Qualunque sia il tasso applicabile, il misuratore moltiplica quindi l'importo per pricing.multiplier, predefinito 1.

Gli abort dei client vengono fatturati anche. Quando un flusso termina senza il frame di utilizzo finale dell'upstream, il misuratore fattura una stima minima di circa quattro caratteri per token di output per il testo già inviato al client, quindi interrompere le richieste in anticipo non consente di aggirare un limite.

Disponibilità di Postgres

La pre-verifica interroga Postgres con un timeout di due secondi. Se l'archivio è irraggiungibile o scade, l'applicazione fallisce aperta per impostazione predefinita: la richiesta procede, il gateway registra un avviso e la risposta non contiene header anthropic-ratelimit-unified-*. Imposta enforcement.fail_closed_on_error: true per fallire chiuso invece, che restituisce lo stesso 429 billing_error ma con il messaggio spend limit unavailable e nessun periodo, ora di reset o header retry-after. Fail-open impedisce a un'interruzione dell'archivio di diventare un'interruzione dell'inferenza; fail-closed garantisce nessuna spesa non misurata.

Avvisi di utilizzo in Claude Code

Claude Code avverte uno sviluppatore mentre si avvicina al suo limite: una volta che l'utilizzo supera il 75%, e di nuovo oltre il 95% del suo limite più consumato. Quando il gateway blocca una richiesta, Claude Code mostra il messaggio 429 del gateway così com'è, incluso il tuo admin.blocked_message.

L'avviso funziona dagli header di risposta:

  • Con v2.1.225 o successivo sul server gateway, ogni risposta /v1/messages riuscita per uno sviluppatore che ha un limite contiene il suo utilizzo del limite e l'ora di reset negli header anthropic-ratelimit-unified-*.
  • Con v2.1.225 o successivo anche sulla macchina dello sviluppatore, Claude Code legge gli header e mostra l'avviso.

Gli header descrivono sempre il limite dello sviluppatore: il gateway elimina gli header di limite di velocità del provider upstream, che descrivono la tua quota condivisa, e non li inoltra mai.

Con v2.1.251 o successivo sulla macchina dello sviluppatore, Claude Code legge anche gli stessi header per mostrare una barra Spend limit in /usage, con la percentuale del loro limite utilizzato e quando si ripristina, e per aggiungere un oggetto rate_limits.spend_limit alla linea di stato di input. Claude Code mostra entrambi come percentuale piuttosto che come importo in dollari e non ha bisogno di nulla più recente di v2.1.225 sul server gateway.

Riferimento Admin API

Gli endpoint di seguito vengono serviti sotto /v1/organizations/spend_limits.

Metodo e percorso Descrizione
GET /v1/organizations/spend_limits Elenca i limiti configurati, facoltativamente filtrati a un scope_type di organization, rbac_group, o user. Query: ?limit=&after_id=&before_id=&scope_type=.
POST /v1/organizations/spend_limits Crea o sostituisce un limite per {scope, period}.
GET /v1/organizations/spend_limits/{id} Recupera un limite per il suo ID con prefisso spl_.
DELETE /v1/organizations/spend_limits/{id} Elimina un limite. Restituisce {type: "spend_limit_deleted", id}.
GET /v1/organizations/spend_limits/effective Limite risolto e spesa da inizio periodo per principale per periodo.
GET /v1/organizations/spend_limits/audit Traccia di mutazione amministrativa, più recente per primo. Query: ?limit=&after_id=.

Le convenzioni rispecchiano l'Admin API di Anthropic:

  • Un type su ogni oggetto
  • ID con prefisso spl_
  • Importi come stringhe di numero intero di centesimi USD; POST rifiuta qualsiasi altra currency con 400
  • L'envelope di errore {type: "error", error: {type, message}, request_id}
  • Un header di risposta request-id su ogni risposta amministrativa, successo o errore; i corpi di errore lo portano anche come request_id

Ogni mutazione scrive una riga prima/dopo a admin_audit nella stessa transazione, attribuita a admin-key:<id> o oidc:<sub>.

Il gateway serve gli endpoint dei limiti di spesa solo. Altre superfici Admin API, come la coda spend_limit_increase_requests, non fanno parte dell'Admin API del gateway.

`/effective`

GET /v1/organizations/spend_limits/effective restituisce lo schema SpendSummary di Anthropic: ogni riga è un principale per un periodo, con il limite risolto, la spesa da inizio periodo e un oggetto actor. Differenze specifiche del gateway:

  • user_id è l'OIDC sub.
  • actor.name e actor.email_address sono null fino alla prima richiesta di inferenza del principale attraverso il gateway. Il gateway non ha una directory utenti; registra i valori ultimi visti dal JWT di sessione di ogni utente.
  • Ogni riga contiene anche un array groups, gli ultimi gruppi IdP visti dal principale. Questa è un'estensione del gateway in modo che un'interfaccia utente amministrativa possa mostrare ogni livello di limite che si applica; i client a forma di Anthropic lo ignorano.
  • Senza un filtro user_ids[], elenca i principali con spesa registrata, perché il gateway non può enumerare tutti i membri dell'organizzazione.

I limiti di origine del gruppo si risolvono rispetto a quei gruppi ultimi visti con lo stesso tie-break group_limit_mode che l'applicazione utilizza, quindi il visualizzatore mostra il limite che effettivamente si applica.

Parametro di query Descrizione
user_ids[] Ripetibile. Filtra a principali specifici per OIDC sub.
period[] Ripetibile. Filtra a righe daily, weekly, o monthly.
sort spend_desc elenca i maggiori spenditori per primi. Richiede esattamente uno period[].
q Filtro di sottostringa senza distinzione tra maiuscole e minuscole sull'OIDC sub, email ultimi visti e nome visualizzato ultimi visti.
limit / page Dimensione della pagina, 1–1000 con un predefinito di 20, e il cursore opaco dalla risposta precedente next_page.

`/audit`

Restituisce la traccia di mutazione del limite di spesa: chi ha modificato quale limite, con snapshot prima/dopo, più recente per primo. has_more è esatto. Questo endpoint segue le convenzioni dell'Admin API locale piuttosto che una forma di dati di prima parte.

Paginazione

L'elenco grezzo pagina per after_id e before_id, che sono ID spl_… mutuamente esclusivi; i risultati sono ordinati per creazione e has_more riflette la direzione di attraversamento. /effective pagina per il token opaco next_page passato indietro come ?page=, con principali ordinati in modo ascendente in modo che le pagine rimangono stabili mentre la spesa viene registrata. limit è 1–1000, predefinito 20, su entrambi. /audit pagina per after_id, l'ID numerico id dell'ultimo evento sulla pagina precedente, e il suo limit predefinito è 100.

Ciclo di vita dei dati

Il gateway contiene quattro tabelle relative alla spesa; una pulizia oraria applica le finestre di conservazione:

Tabella Contenuti Conservazione
spend Contatori da inizio periodo per principale in centesimi admin.spend_retention_months, predefinito 13
spend_limits I limiti configurati Fino all'eliminazione tramite l'API
admin_audit La traccia di mutazione admin.audit_retention_days, predefinito 365
principal_emails Email ultimi visti di ogni principale, nome visualizzato e gruppi IdP. Contiene PII. admin.identity_retention_days dall'ultima attività, predefinito 90

Quando uno sviluppatore se ne va, elimina qualsiasi limite per utente tramite DELETE /v1/organizations/spend_limits/{id}; la loro spesa e le righe di identità invecchiano sulle finestre di conservazione di cui sopra. Per cancellare una persona immediatamente, per offboarding o una richiesta di accesso ai dati del soggetto (DSAR), esegui DELETE FROM principal_emails WHERE principal = '<sub>' direttamente contro il database del gateway. Questo rimuove l'unica tabella che contiene la loro email, nome e gruppi. Le righe spend e admin_audit fanno riferimento solo all'OIDC sub pseudonimo e invecchiano sulle loro finestre.