Limites de gastos limitam quanto cada desenvolvedor pode gastar através do seu gateway de aplicativos Claude em um determinado dia, semana ou mês. Quando um desenvolvedor ultrapassa seu limite, o gateway retorna 429 na próxima solicitação e os bloqueia até que o período seja redefinido ou um administrador aumente o limite. Use limites de gastos para dar a cada desenvolvedor, grupo ou toda a organização um teto de gastos em uma credencial que todos compartilham.
Um gateway de aplicativos Claude encaminha toda a inferência através de uma credencial upstream compartilhada, portanto a fatura do seu provedor atribui tudo a essa credencial, não a desenvolvedores individuais. Sem limites por desenvolvedor, uma frota de agentes descontrolada pode gastar todo o compromisso da organização. Limites de gastos são a visão por desenvolvedor do gateway e o disjuntor em cima dessa fatura compartilhada.
Defina um limite
Com o bloco admin: configurado em gateway.yaml, o gateway fornece uma API de administrador em /v1/organizations/spend_limits e aplica limites em tempo real em cada solicitação de inferência. Os limites em si são definidos através dessa API, não em gateway.yaml; cada solicitação POST /v1/organizations/spend_limits cria ou substitui um limite de {scope, amount, period}. A API espelha as formas de transmissão dos endpoints de limites de gastos da API de Administrador pública da Anthropic, portanto um cliente HTTP escrito contra esse contrato pode direcionar o gateway alterando sua URL base.
Esta solicitação define um padrão em toda a organização de $500 por mês para cada desenvolvedor:
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"}'
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 | Valores | Descrição |
|---|
scope.type | user, rbac_group, organization | user direciona um desenvolvedor pelo seu OpenID Connect (OIDC) sub, o ID de usuário estável que seu provedor de identidade atribui; passe-o como scope.user_id. rbac_group direciona um grupo IdP por nome; passe-o como scope.rbac_group_id. organization é o padrão em toda a organização. O gateway aceita todos os três; o POST público da Anthropic é apenas para usuários hoje. |
amount | String de número inteiro de centavos USD, ou null | null é ilimitado. "0" é um limite zero, que bloqueia todas as solicitações. |
period | daily, weekly, monthly | Um escopo pode conter um limite por período, e cada um é aplicado independentemente: um desenvolvedor é bloqueado se ultrapassar qualquer um deles. |
admin.group_limit_mode: max inverte o desempate de múltiplos grupos para menos restritivo em vez disso.
Autentique-se na API de administrador
Envie um dos seguintes:
- Um cabeçalho
x-api-key correspondendo a uma chave em admin.write_keys para acesso total, ou admin.read_keys para acesso somente GET. Cada chave carrega um id que aparece no log de auditoria como admin-key:<id>, portanto dê ao Terraform, CI e cada automação a sua própria.
- Um token de portador do gateway cujo
groups claim inclui um dos admin.admin_groups. Este é acesso total e é auditado como oidc:<sub>, portanto prefira-o para administradores humanos.
Como a aplicação funciona
Em cada solicitação /v1/messages, o gateway resolve os limites do desenvolvedor e o gasto até a data do período em uma consulta Postgres. Se estiverem acima de qualquer limite, a solicitação retorna 429 com error.type: billing_error e o cabeçalho x-should-retry: false. A mensagem é spend limit reached, seguida pelo seu admin.blocked_message se definido.
/v1/messages/count_tokens é isento. A contagem de tokens é gratuita, portanto é executada independentemente do estado do limite.
Após cada resposta, um medidor de uso lê contagens de tokens da resposta conforme ela é transmitida para o cliente, precifica-os ao preço de lista USD e incrementa contadores Postgres para todos os três buckets de período. O medidor é um único leitor no fluxo, portanto os bytes do cliente não são tocados e uma falha de medição não quebra a resposta.
Limites de gastos estimam gastos a partir de contagens de tokens ao preço de lista USD; eles são um disjuntor, não uma fatura. Para faturamento autoritário, reconcilie contra o relatório de uso do seu próprio provedor, como a API de Administrador de Uso e Custo da Anthropic, logs de invocação no Bedrock ou Cloud Monitoring no Google Cloud.
A precificação usa a mesma tabela que o Claude Code CLI usa para sua própria exibição de custo, com a mesma canonicalização de ID de modelo em formulários Anthropic, Bedrock (us.anthropic.…-v1:0), Agent Platform (claude-…@date) e Foundry ID. Um ID de modelo que a tabela não consegue colocar, como um nome de implantação Foundry ou um ARN de perfil de inferência, é precificado no nível padrão de modelo desconhecido de $5/$25 por milhão de tokens de entrada/saída em vez de zero, portanto um ID não reconhecido não pode contornar um limite indo sem medição. O gateway avisa na inicialização e uma vez por ID em tempo de execução quando um modelo é precificado através do fallback.
Aborts de cliente também são faturados. O upstream relata tokens de saída apenas no quadro terminal do fluxo, portanto um fluxo abortado não os carrega. O medidor mantém uma estimativa de piso conservadora do tamanho do conteúdo transmitido, cerca de quatro caracteres por token, e a fatura quando e apenas quando o quadro de uso terminal está faltando. Um fluxo completo sempre fatura a contagem relatada pelo upstream. Sem isso, um desenvolvedor limitado poderia transmitir saída e abortar cada solicitação imediatamente antes do final, gastando sem nunca ser contado.
Disponibilidade do Postgres
A pré-verificação consulta o Postgres com um tempo limite de dois segundos. Se o armazenamento estiver inacessível ou expirar o tempo limite, a aplicação falha aberta por padrão: a solicitação prossegue e o gateway registra um aviso. Defina enforcement.fail_closed_on_error: true para falhar fechado em vez disso, que retorna o mesmo 429 billing_error com a mensagem spend limit unavailable. Falha aberta mantém uma interrupção de armazenamento de se tornar uma interrupção de inferência; falha fechada garante nenhum gasto sem medição.
Referência da API de administrador
Os endpoints abaixo são servidos em /v1/organizations/spend_limits.
| Método e caminho | Descrição |
|---|
GET /v1/organizations/spend_limits | Listar limites configurados. Consulta: ?limit=&after_id=&before_id=. |
POST /v1/organizations/spend_limits | Criar ou substituir um limite para {scope, period}. |
GET /v1/organizations/spend_limits/{id} | Buscar um limite por seu ID com prefixo spl_. |
DELETE /v1/organizations/spend_limits/{id} | Deletar um limite. Retorna {type: "spend_limit_deleted", id}. |
GET /v1/organizations/spend_limits/effective | Limite resolvido e gasto até a data por principal por período. |
GET /v1/organizations/spend_limits/audit | Trilha de mutação de administrador, mais recente primeiro. Consultas: ?limit=. |
- Um
type em cada objeto
- IDs com prefixo
spl_
- Quantidades como strings de número inteiro de centavos USD;
POST rejeita qualquer outro currency com 400
- O envelope de erro
{type: "error", error: {type, message}, request_id}
- Um cabeçalho de resposta
request-id em cada resposta de administrador, sucesso ou erro, correspondendo ao request_id do corpo
Cada mutação escreve uma linha antes/depois para admin_audit na mesma transação, atribuída a admin-key:<id> ou oidc:<sub>.
O gateway serve os endpoints de limites de gasto apenas. Outras superfícies da API de Administrador, como a fila spend_limit_increase_requests, não fazem parte da API de administrador do gateway.
/effective
GET /v1/organizations/spend_limits/effective retorna o schema SpendSummary da Anthropic: cada linha é um principal para um período, com o limite resolvido, gasto até a data do período e um objeto actor. Diferenças específicas do gateway:
user_id é o OIDC sub.actor.name e actor.email_address são null até a primeira solicitação de inferência do principal através do gateway. O gateway não tem diretório de usuários; ele registra valores vistos pela última vez do JWT de sessão de cada usuário.- Cada linha também carrega um array
groups, os últimos grupos IdP vistos do principal. Esta é uma extensão do gateway para que uma UI de administrador possa mostrar cada nível de limite que se aplica; clientes em forma de Anthropic a ignoram.
- Sem um filtro
user_ids[], ele lista principais com gasto registrado, porque o gateway não consegue enumerar todos os membros da organização.
Limites originários de grupo são resolvidos contra esses últimos grupos vistos com o mesmo desempate group_limit_mode que a aplicação usa, portanto o visualizador mostra o limite que realmente se aplica.
| Parâmetro de consulta | Descrição |
|---|
user_ids[] | Repetível. Filtrar para principais específicos por OIDC sub. |
period[] | Repetível. Filtrar para linhas daily, weekly ou monthly. |
sort | spend_desc lista os maiores gastadores primeiro. Requer exatamente um period[]. |
q | Filtro de substring insensível a maiúsculas/minúsculas sobre o OIDC sub, último email visto e último nome de exibição visto. |
limit / page | Tamanho da página, 1–1000 com padrão de 20, e o cursor opaco da resposta anterior next_page. |
q= e user_ids[]= usam strings de consulta GET, portanto qualquer proxy frontal ou balanceador de carga captura-os em seus logs de acesso. Se sua política de log de PII for rigorosa, limpe esses parâmetros lá.
/audit
Retorna a trilha de mutação de limite de gasto: quem mudou qual limite, snapshots antes/depois e a razão opcional, mais recente primeiro. has_more é exato. Este endpoint segue as convenções da API de Administrador local em vez de uma forma de transmissão de primeira parte.
A lista bruta pagina por after_id e before_id, que são IDs spl_… mutuamente exclusivos; os resultados são ordenados por criação e has_more reflete a direção da travessia. /effective pagina pelo token opaco next_page passado de volta como ?page=, com principais ordenados em ordem crescente para que as páginas permaneçam estáveis enquanto o gasto está sendo registrado. limit é 1–1000, padrão 20, em ambos.
Ciclo de vida dos dados
O gateway mantém quatro tabelas relacionadas a gastos; uma varredura horária aplica as janelas de retenção:
| Tabela | Conteúdo | Retenção |
|---|
spend | Contadores até a data do período por principal em centavos | admin.spend_retention_months, padrão 13 |
spend_limits | Os limites configurados | Até deletado via API |
admin_audit | A trilha de mutação | admin.audit_retention_days, padrão 365 |
principal_emails | Último email visto de cada principal, nome de exibição e grupos IdP. Contém PII. | admin.identity_retention_days desde última atividade, padrão 90 |
identity_retention_days é deliberadamente mais curto que spend_retention_months: uma identidade desprovisionada para de se atualizar e envelhece, enquanto seus contadores de gasto anônimos permanecem para relatórios ano a ano.
Quando um desenvolvedor sai, delete qualquer limite por usuário via DELETE /v1/organizations/spend_limits/{id}; seu gasto e linhas de identidade envelhecem nas janelas de retenção acima. Para apagar uma pessoa imediatamente, para offboarding ou uma solicitação de acesso de assunto de dados (DSAR), execute DELETE FROM principal_emails WHERE principal = '<sub>' diretamente contra o banco de dados do gateway. Isso remove a única tabela contendo seu email, nome e grupos. As linhas spend e admin_audit referenciam apenas o pseudônimo OIDC sub e envelhecem em suas próprias janelas.
